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Welcome 
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MAGAZINE 


wise maker called Ben Driscoll once said: 
“Tf you ever code something that ‘feels 
like a hack but it works,’ just remember 
that a CPU is literally a rock that we tricked 

into thinking.” 

This month, we’re putting that ‘hack that works’ 
concept into the trickiest of thinking concepts: 
artificial intelligence (Al). 

AI works right at the coalface of computing. It’s 
exciting, complicated, baffling, and brilliant. But you 
don’t need a PhD in neural networks to get our Al SUBSCRIBE 
services up and running. These projects are picked to Ss ae PT TTS 
help you understand AI with the minimum of fuss. GIN TEIR GOA 

The Raspberry Pi is a perfect fit for Al. Because SEE PAGE 14 FOR DETAILS piste Mt 
while you might need a fast CPUs and multiple GPUs 
to create AI models (the decision-making plans), you 
can run models on microcomputers like the Raspberry 


Pi and access powerful AI tools via cloud services. THIS MONTH: 
And the Raspberry Pi acts as the interface 
to physical computing hardware, turning 
those mysterious AI models into practical 16 ARTIFICIAL INTELLIGENCE 
real-world projects. Get to grips with Al using a Raspberry Pi 
Al is one of the most misunderstood technologies 299 GHOST DETECTOR 


in the modern world. A sprinkling of AI dust ona i 
The non-existence of spirits won't stop our maker 
physical computing project can create a seemingly 


magical device; read on and you’ ll discover how 66 MAKING MUSIC 
down-to-earth Al really is. Turn your Pi into ahome recording studio 
Lucy Hattersley 88 MEDICAL MARVEL 

Editor We chat to inventive nurse Ernesto Holguin 
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Some of the tools and techniques shown in The MagPi magazine are dangerous unless used with skill, experience, and appropriate personal protection equipment. While we 
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Latest OS update gets setup wizard, app store and The MagPI 


The 

new setup 
wizard guides 
you through 
the essential 
setup process 


he Raspberry Pi 
Foundation has released a 
new version of Raspbian, 
including a setup wizard for the 
first time. 
As Simon Long, Senior Principal 
Software Engineer, Raspberry 
Pi Foundation, explains about 
previous versions: “When anew 
user first boots up a new Pi... they 
might not have much of an idea 
what they ought to do next. 
“With the new update,” 
Simon continues, “a simple 
setup wizard runs automatically 
to walk you through the basic 
setup operations.” 
Simon tells us, “The essentials 
are getting the keyboard and 


‘> & Welcome to Raspberr 
— wr 


$6 © 


language right (because otherwise 
input and output don’t work 
properly), setting the WiFi country 
(as otherwise you can’t use the 
network), changing the password 
(basic security), checking for 
updates (basic security and 
reliability), and establishing a 
network connection (required to 
check for updates).” 
Personalisation options, such as 
setting the desktop background, 
weren’t included in the setup 
wizard, as “the system will work 
perfectly fine without [them].” 
Setting the WiFi country 
correctly is important since the 
release of the Raspberry Pi 3B+, as 
Simon clarifies: “In order for 5G 


WiFi hardware to be certified for 
use, it must not radiate unless a 
country has been set.” 

The new version of Raspbian 
also includes a Recommended 
Software ‘app store’ for the first 
time — see the ‘Raspbian App 
Store’ box for more details. 


A new PDF viewer 
Raspbian has used Xpdf since 
its inception, but this venerable 
application has become dated in its 
look, capabilities, and performance. 
The new version of Raspbian 
has replaced Xpdf with qpdfview 
because, Simon reveals, the 
default Raspbian PDF viewer 
“needed to render fast, preload 
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pages, have a modern UI... and to 
fit our look and feel.” 

The more well-known Okular 
wasn’t chosen; Simon explains 
that “the fact that it’s a 200MB 


install, including an older version 


Change Password 


a PDF file,” Simon confirms. 
“Look in the ‘MagPi’ directory in 
your home directory ‘pi’.” You’ ll 
still be able to download the PDF 
version of this magazine from 
mMagpi.cc/issues. 


Raspbian also includes a 
Recommended Software 
app store for the first time 


of the Qt toolkit than we already 
ship” counted against it. 

Simon continues, “qpdfview is 
Qt based, which is non-ideal - our 
Standard GUI toolkit is GTK, but I 
was able to hack the Qt theming to 
closely resemble GTK.” 

You might also be pleased to 
hear that “we are now including 
the latest issue of The MagPi as 


'@ mse 


Ma "S  couthers 


The official Raspberry Pi magazine 


Upgrade Raspbian through the 
Terminal in the usual way (sudo 
apt-get update; sudo apt- 
get dist-upgrade). To view the 
Startup wizard and Recommended 
Software, download the image 
from magpi.cc/PVNGfh. 

The x86 desktop version of 
Raspbian has also been updated 
with “most of the changes”. 
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HOME AUTOMATION 
WITH RASPBERRY PI 


— Practical nroiects to take vour home into the future 


The new PDF viewer is a welcome update from Xpdf, and there's a digital copy 
of The MagPi magazine waiting in your ‘pi home directory to read 
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Raspbian now 
prompts users to 
change the password 
when they first boot up 
the Raspberry Pi 


Recommended Software 


‘a All Pregrerns 


The new version of Raspbian also includes a new 
app store called Recommended Software. This is 
a separate application to the software manager, 
allowing Raspbian users to select which of the 
previously default software to install. 

Not everyone needs BlueJ, Node-RED or 
VNC Viewer, so including these by default 
only leads to a larger download, clutter, 
and confusion. Installation is now optional. 

The Recommended Software app brings 
together all of the software that, as Simon notes, 
“several third-party companies have generously 
offered ... in some cases giving free licences,” as 
well as software recommended for use on a Pi by 
the Raspberry Pi Foundation. 

For example, a Mathematica licence would 
normally cost “several hundred pounds,” says 
Simon, while there's also a “free licence for 
RealVNC Viewer and Server." 

The Recommended Software application can 
be found in the Preferences menu of the new 
Raspbian release. To add the application to 
your Raspbian install, use the command sudo 
apt-get install rp-prefapps. 
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Applications open, challenges announced 


Pi Wars® 


THE Rasa Pi Robo Tc: CHALLENGE CORRE 


he application process for 
Pi Wars 2019 is now open, 
and this year sees the first 
Pi Wars theme: space exploration! 
Pi Wars co-organiser Mike Horne 
confirms: “This is the first time we 
have themed Pi Wars, in honour of 
the 50th year since the first moon 
landing.” The idea came from 
previous winner Dave Pride. 
The theme means cosmetic 
changes to both the challenges 


This 1s the first ttme we have themed 
Pi Wars, 1n honour of the 50th year since 


the first moon landing 


and the venue, which remains as 
the William Gates Building of the 
Cambridge Computer Laboratory. 
“Lots of painting of the courses is 
going to occur over the summer,” 
Mike tells us. 


Challenger 
The space theme introduces new 
challenges, but Mike says that 
“the rules are pretty similar to 
before, with a few tightened up and 
few loosened.” 

For example, the new Hubble 
Telescope Challenge is based 
on 2018’s Over the Rainbow, 
where robots needed to identify 
coloured balls and drive to them in 
sequence. “This was the hardest 
course by a long way,” Mike 
reveals. “We will be making the 
targets larger, but have not yet 
finalised that.” 
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Space Invaders is based on the 
Duck Hunt challenge, “with the 
same skills required to score.” 
The Spirit of Curiosity challenge 
involves driving your robot over 
an obstacle course, collecting 
a sample (which “will vary in 
size, but not by much’) and 
driving back. 


Re-entry 

Pi Wars 2018 received “over 150 
entrants,” Mike confirms, “which 
had to be cut down to just 76, plus 
reserves.” This involves a “very 
hard couple of days”, as Mike tells 
us that “we cannot just choose 
previous entrants as we want 

to make space for noobs.” 

Mike has this advice for your 
application form: “Ensure the 
entrants show their enthusiasm 
[and] we like detail.” 


The Pi Wars 
2018 obstacle 
course drewa 
crowd of roboteers 
and supporters 


Pi Wars 2019 will take place on 
30 and 31 March, so head over to 
piwars.org to read about rules, 
challenges, and to apply. Keep up 
to date with news via the mailing 
list or Twitter @PiWarsRobotics. 


= 


Entrants don't 
need to use expensively 
assembled robots; LEGO 
is a decent material for a 
modifiable challenger 
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CDP Studio is a development platform for industrial control systems, now coming with a free 
version for non-commercial use. The system can run on a Raspberry Pi, supports C++, open source 
libraries and has a large feature toolbox including GPIO, I2C and MQTT. Its built in GUI design tool 


and features lets you code less and do more. 
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COLOUR 
-CODED 
PI ZEROS 


Making making easier 


i Supply has released a 

pair of Pi Zero boards with 

colour-coded GPIO pins, 
as well as a separate colour-coded 
header, to make your mini-builds a 
bit easier. 

As John Whiting, director of 
marketing for Pi Supply, explains, 
“A lot of users have struggled in 
the past remembering the GPIO 
layout, so the coloured header is 


DIDDY BORG » 


The v2 proves red ones are faster! 


ne of the most popular 

robot kits has received an 

update, with more powerful 
motors and a newly designed 
chassis that’s still compatible with 
add-ons such as the touchscreen 
and camera mounts. 

Timothy Freeburn, director of 
Freeburn Robotics and PiBorg, 
explains that “the DiddyBorg v2 
Red is essentially a high-speed 
version of the DiddyBorg.” 

We reviewed the DiddyBorg V2 in 
The MagPi #70 (magpi.cc/70). 

While Timothy and the design 
team “wanted the DiddyBorg v2 
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Above The colour-coded 
headers make it easier 
to connect sensors and 
outputs to your Pi Zero 


a low-cost way of not having to 
remember the layout or go off and 
Google it.” 

The colour-coding follows the 
usual convention, where red is 
+5 V, yellow is +3.3V (also referred 
to as 3V3), black is ground, blue is 
DNC (or reversed I?C), and green 
shows the GPIO pins. 

“The reaction has been great”, 
John tells us. “We’ve had many 


users say how helpful this 
GPIO header is, particularly 
for beginners.” 

John adds that “we hope to 
see a colour-coded header on 
the main Raspberry Pi boards in 
the future!” 

The colour-coded Pi Zero 1.3 
costs £9.16, the Pi Zero W £12.50, 
and the header only £1.25, all from 
uk.pi-supply.com. 


The new DiddyBorg v2 _-_—_— 
is now as fast as the larger, ii —— 
racier MonsterBorg but still “a —— 
has plenty of torque SS 


Red to be a similar speed to our 
very popular MonsterBorg kit”, 
merely changing the gearing on 
the existing DiddyBorg motors 
would increase the speed, “but the 
torque would come right down, 
which would have made tank 
steering impossible.” 

The extra grunt of the DiddyBorg 
v2 comes from six 590rpm, 28mm 
motors. Timothy notes that “you 
can easily upgrade the motors” of 
a DiddyBorg v1 with six P28UK12 
motors for £64.80 (total) from 
piborg.org. The new DiddyBorg v2 
Red costs £220 from the same site. 
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Light, secure, and fast 


he latest versionof Alpine — size of ‘around 130MB’ while 


Me ; , 
Pimtixe ai mdependent, a container requires no more magpi.cc/hNHkYT 
non-commercial, general- than 8MB’. 
purpose Linux distribution Alpine Linux is said to be To make a point about the nature of humour, Tom 
designed for power users’, ‘designed with security in mind’ Murphy VII ‘reverse-emulated’ an unmodified NES to 


supports 64-bit Raspberry Pi by using an ‘unofficial port of run SNES games via a Raspberry Pi embedded in the 
models, including the Pi 3B+. ersecurity/PaXx’ while ‘all userland NES game cartridge. 

While version 3.2 of Alpine binaries are compiled as position- 
Linux supported the 32-bit independent executables (PIE) 


Alpine Linux 1s a sound 
choice for a home PVR, or 
an 1SCSI storage controller 


Raspberry Pi 2, the new release with stack-smashing protection. ’ 
; ; magpi.cc/plLSXSC 
uses an aarch64 image to support Which surely all makes Alpine 
64-bit Pi devices — you can Linux a sound choice for ‘a What do you get if you cross a Tesla engine with a 1981 
download this image for free from home PVR, or an iSCSI storage Honda Accord? Not much, unless you then integrate 
alpinelinux.org/downloads. controller, a wafer-thin mail a Raspberry Pi to unleash the 536 hp and achieve 
Alpine Linux ‘is built around Server container, or a rock-solid 0-60 mph in 2.48 seconds! 
musl libc and Busybox’, giving embedded switch’, according to 
the distro a claimed install the About page. 


Small. Simple. Secure. 


ree Alpine Linux moa Seednly-ouented, ightveighlLinux disty bution based on must bce and busybox 
# PS 
fj = A ia 


all 
“A 
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AF 7. “ie Tim Jacobs revived the thrill of instant photography 
As OIL aU are eee aIOS EL by incorporating a Pi Zero, a £2 webcam, and a tiny 
for making Pi-based single-use devices thermal printer in an old Polaroid camera body. 
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the perfect sourdough bread. He 


ustin Lam, a mechatronics 
engineer (in training), had 


a problem: how to make 


applied his knowledge of Linux, 


the Raspberry Pi, and image and 


Statistical analysis to predict 


peak fermentation to achieve the 


perfect crumb. 


Sourdough bread uses slightly 
unpredictable ‘wild yeast’ rather 
than the “stable and consistent” 
instant dry yeast used in standard 
bread, Justin explains. But, instant 
yeast “lacks the complex flavours 


that wild yeast [in] sourdough 
starter provides.” 


To bake a sourdough loaf, you 
need to take some starter (a mixture 
of flour and water, exposed to the air 
to ‘catch’ the wild yeast) and ‘feed’ 
it with some flour and water. You 
then have to wait for this mixture 
to achieve maximum fermentation 


PI-MONITORED 
SOURDOUGH 
STARTER 


Use a Pi for the perfect loaf 


before proceeding to make a loaf. 
If you start making that bread 
dough too early or too late in the 
fermentation process, the resultant 
loaf won’t be good eating. 

Even worse, Justin tells us 
that while “the time to max 
fermentation will be consistent” 
if you use the same volumes of 
starter and feed, “temperature and 
humidity [changes] throughout the 
season will alter” the time until 
maximum fermentation. 


BreadCam 

Justin’s solution was to monitor 
the rise of the starter with a Pi 
Zero fitted with a Raspberry Pi 
camera. Justin says, “I was able to 
leverage my previous experience 
with image analysis” to build 

a system that could accurately 
monitor the fermentation process 


Justin used the Pi Zero “for speed 
of development” and because “the 
RPi community is a significant 
advantage over other platforms.” 

He then used a ‘threshold 
algorithm’ to measure the level of 
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in a jar. the starter in the jar, graphing the The Pi Zero 
: i ; . with camera was 
rise over time. His starter typically ppeioat pe 


achieved peak fermentation after 
eight hours, with a window of 


measure; the jars of 
sourdough starter 
were backlit in the 


around one hour to start forminga _finalproject 
loaf-sized dough to bake. . 
Justin says 
Justin says the analyses he did his analyses of 
«¢ ) the visual and 
were “extremely simple”, using pa ee neenerees 


Scikit-learn. The details are well 
documented on Justin’s blog - 
see magpi.cc/cCGydQ. 


were “extremely 
simple” — perhaps 
‘relatively’ might be 
more accurate? 


2018-05-29 Levain Timelapse/2012-05-20_08-34.24_(97) 
Cropped Parsed Grephed 
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HACKSTER AND ARM AUTONOMOUS ROBOT CHALLENGE 


HACKSTER 


AND ARM 


AUTONOMOUS ROBOT 
CHALLENGE 


ackster has joined with 
processor designer ARM 
to launch the Autonomous 
Robot Challenge, ‘to push the limits 
of what low-cost, open-source 
hardware and deep learning’ can do 
for humanity. 

The basics of the challenge are to 
design a machine based around an 


diving systems has arrived. ... We 
want to see how society can benefit 
from these new capabilities and 
combine the trifecta of low-cost 
UAVs, Al, and [machine learning] 
into new inventions.” 

Rex St John, Senior Manager, IoT 
Ecosystem at ARM, adds: “We feel 
there is a good side to the topic 


Autonomously transport a 
package 1n an urban, rural, 
or underwater environment 


ARM device (such as a Raspberry 
Pi) that can do at least one of 
these two tasks: ‘autonomously 
transport a package in an urban, 
rural, or underwater environment’; 
‘autonomously assist in a real- 
world scenario’. 

Adam Benzion, CEO of Hackster, 
explains, “We feel that the era of 
working drones, driving machines, 
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of autonomous machines that we 
want to highlight and inspire the 
creativity of developers to think 
more broadly about how this low- 
cost AI technology can be used for 
positive reasons.” 

You can enter by “submitting 
code, schematics, and BOM [bill of 
materials],” reveals Adam, adding 
that “it has to be a functional 


Above Use an 
ARM-powered 
device, such as 
the Raspberry 

Pi, to invent an 
autonomous robot 


Win some goodies with your 
autonomous vehicle design 


project. Not perfect, but inventive 
and working.” 

The Autonomous Robot Challenge 
is offering some great prizes for 
various categories, such as an 
X PlusOne HD drone for the two 
projects making best use of Al, anda 
Geth-spider-like Robugtix T8X robot 
for the two most creative projects. 
See magpi.cc/TzzoWh for details. 

Participation is open until 
30 September 2018, 11:59pm Pacific 
Time. Winners will be announced 
by 15 October 2018. 


Below The open- 
source DonkeyCar 
is a suggested 
device that might 
form a useful basis 
for your project. See 
donkeycar.com for 
more details 
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feature 


JOSE MARCIAL PORTILLA 


Jose is the Head of Data Science 
at Pierian Data Inc, and an Al 
expert. He has several Al learning 
courses you can find here: 


WHAT IS Al? 


The term ‘artificial intelligence’ There are also instances of intelligence tasks, including 
was coined in 1956 at a workshop what is commonly referred to as creating a computer that can 
in Dartmouth College by John ‘narrow Al’ tasks; these include defeat the world’s best Go 
McCarthy, a few years after Alan more complex applications players ( ) 
Turing had written his now famous of neural networks (a specific developing self-driving cars 
paper ‘Computing Machinery and framework of machine-learning with WayMo ( ) 
Intelligence’ in 1950. algorithms modelled after and creating a Google Assistant 
A common misunderstanding biological neurons). These narrow _ capable of calling and creating 
is to conflate the terms AI tasks can include things appointments with interactions 
‘machine learning’ and ‘artificial such as image classification, ( ). These 


intelligence’. Machine learning 


is the use of algorithms that have We've recently SeCeCT) developments 


the ability to learn from a data 

source, allowing the algorithm 

Sten nen totam from Google in these sort of narrow 
or decisions based on that 


data. Examples include spam artificial intellig ence tasks 


email classification, housing 


price prediction, and product language translation, and face developments help pave the 
recommendations in e-commerce. recognition. There have been way towards the creation of 
While machine learning is huge advancements in this field ‘strong AI’, which are artificially 
extremely useful, we typically over the past few years due to intelligent systems that become 
don’t think of these single a large increase in availability indistinguishable from the 
machine-learning algorithms as in computational power, intelligence of humans. This is 
‘intelligent’ in the same way we especially due to advancements a future where AI can begin to 
think of humans as ‘intelligent’. in GPU performance. develop music, create works of art, 
This is why machine learning We have recently seen and hold anormal conversation 
is a subset of the larger goal of developments from Google in with a human. 
artificial intelligence. these sort of narrow artificial While there have been many 


developments in these individual 
topics, we’re still far away from 

a truly artificially intelligent 
system, but working on these 
more narrow AI problems can help 
researchers solve the issues that 
may face them when pursuing 
general strong Al. 


AlphaGo Zero learns to play Go (a board 
game) without help. After 70 hours it 
becomes a superhuman player and after 40 
days trains itself to become, arguably, the 
best Go player on Earth magpi.cc/oSPVEz. 
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feature 


YOU'LL NEED 


OpenCv 
Pj Camera Module 


Full code 


The OpenCV (Open Source Computer 
Vision) Python library can add 
some fairly heavyweight visual AI 
to your Raspberry Pi robot. This 
hugely powerful library has over 
2500 different functions, including a 
comprehensive set of both classic and 
state-of-the-art computer vision and 
machine-learning algorithms. These 
algorithms can be used to detect and 
recognise faces and identify and track 
objects. In this example, we’ll get you 
started by showing how OpenCV can 
be used to detect a line and how we 
can then train a robot to follow it. 


August 2018 


Setting up OpenCV 
Undoubtedly the trickiest 
part of the whole process is getting 

OpencCV installed and running on 

your Raspberry Pi. The installation Capture an Image 


process depends on which Pi/ OS Capturing images is done with the 
setup you are using. Fortunately, picamera.capture() function. 
there are some very good guides We set the resolution fairly low 
out there, including thisone bythe (320x240) as this keeps the 

very awesome Adrian Rosebrock: image size small and lowers the 


processing power required to 
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analyse each one. Once the image 
is captured, we also then crop it to 
ensure we get just the central part 
that we’re interested in. 


Blur the image 

As we’re not really interested in 
the actual details of the image, we 
apply a Gaussian blur on the whole 
thing to blur out unnecessary 
details. This helps level out any 
noise in the image. Don’t worry 
about the name - this is just an 
OpencCV function. 


Use findContours() function 
to find the line 

Firstly, we make a negative of the 
image as this makes it easier for 
OpenCV to detect edges. We then 
use the findContours() function 
to find the edges of the line. With 
some simple maths, we can then 
work out exactly where in the 
image the line appears. 


Let’s get moving 

Now we know where in the image 
the edges of the line are, we 

can instruct our robot to move 


accordingly. There is some very 
simple logic that can be applied at 
this point. The pseudocode below 
should help. 


if LINE in centre of image: 
GO STRAIGHT ON 


if LINE is on left of image: 
TURN LEFT 


if LINE is on the right of 
the image: 
TURN RIGHT 


This will work, but you can get a 
lot more subtle and complex than 
this if you want. For example, 
speed for both turning and driving 
can be altered depending on how 
far away from the centre the 
line is. 

Now, it doesn’t matter what 
robot platform you use, (think 
CamjJam Edukit or the Tiny 4WD 
from Coretec Robotics) all of the 
above will remain the same. It is 
only the instructions to actually 
drive the motors that will change 
depending on your setup. 

A full version of the code 


described above can be found here: 


feature 


FURTHER ADVENTURES 
SOMEWHERE OVER 
THE RAINBOW! 


There is much, much more that you can do 
with OpenCV. In the ‘Somewhere Over the 
Rainbow’ event in Pi Wars this year, robots had 
to autonomously locate and then drive to four 
different coloured balls set in the corners of a 
1.2m square ‘arena’ (Some teams were more 
successful at this than others!) The colour/object 
tracking teams used was mainly OpenCV-based 
and takes a similar approach to finding a line. 
Except it’s a ball. And there's four of them. And 
they're all different colours! 
magpi.cc /aUzwfk 
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— 
IMAGE 


WIL 


icrosoft’s Computer Vision among other features. Pricing is The image may either be a URL or 
M Cognitive Service is a free for up to 5000 transactions a file. The visual features include: 
feature-rich, cloud-based per month, and thereafter $1 or Categories, Tags, Description, 
API providing image analysis that less per 1000 transactions for Faces, ImageType, Colour, and 
can be easily and quickly integrated core features. Adult. Additional details may also 
into your project. In addition to be requested such as identifying 
providing a description of what Senda pictu re celebrities and landmarks. A full 
it ‘sees’, the service is able to In order to get started with the list of all the options and what 
categorise and tag images, detect Computer Vision service, an each provides is available on 
human faces, and recognise text, API key is required and may be the API documentation page at 
obtained at . ; 
Using the API is simply a matter The recognition.py listing is an 
of sending a POST request with example in Python for requesting 
the API key, an image, and a list a description of an image stored 
of the desired visual analysis locally in the file /tmp/image.jpg. 
features, then processing the The returned result will be of 
returned result. the form shown below: 
Q1. { 


@2. "description": { 


@3. VCAPELONS. <4 
04. { 
"text": "The description of the image appears here", 
Q5. "confidence": 23 349872: 
06. } 
07. ] 
68. }, 


99. "requestid": "c11894eb-de3e-451b-9257-7c8b168073d1", 
160. "metadata": { 


ci "height": ale 
12. "width": ; 
a3. "format": "Jpeg" 
14. } 

15. } 
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The basics of this project can be applied 
to build a ‘Seeing Wand’, a project that 
tells you what it’s being pointed at! You 
can find out more details on how to build 

one here: 

The wand was built to help a blind person 
‘see’ a bit more of the world around them 
— it's a bit of a makeshift contraption 
though, using a breadboard and a PVC 
tube. Still, it's pretty wonderful. 


In order to learn more about the 
Computer Vision service and test it 
out using your own images (without 
having to write code if you wish), 
check out: 
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62. 


@3. 
04. 


05. 
06. 
07. 
08. 
09. 
10. 
a1, 
12, 
13. 
14. 
15. 
16. 
17. 
18. 
19; 


20. 
21. 


22. 


23. 
24. 
25. 


26. 
27. 
28. 
29. 
30. 


LANGUAGE: 


DOWNLOAD: 


. #!/usr/bin/python 
import httplib, urllib, base64, json, re 


# CHANGE {MS_API KEY} BELOW WITH YOUR MICROSOFT VISION API 
KEY 
ms_api_key = "{MS_API_KEY} 


# setup vision API 

headers = { 
‘Content-Type’: ‘application/octet-stream', 
"Ocp-Apim-Subscription-Key': ms_api_key, 


} 

params = urllib. ({ 
"visualFeatures': ‘Description’, 

}) 


# read image 
body = ('/tmp/image.jpg', "rb"). () 


# submit request to API and print description if successful 
or error otherwise 
Ry: 

conn = httplib. ('westcentralus.api. 
cognitive.microsoft.com' ) 

conn. ("POST", "/vision/v1.@/analyze?%s"%params , 
body, headers) 

response = conn. () 

analysis=json. (response. ()) 

image caption = analysis["description" ]["captions" |[@] 
["text"]. () 

conn. () 

print image caption 


except dowel 
print e.args 
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Active speakers 
USB microphone 
eliza,py 


Oice assistants are all the 
V rage these days — but most 
of them rely on cloud 
services requiring an internet 
connection, which may cause data 
privacy issues and obscure their 
inner workings. 


Installation 

Most of the more advanced 
speech-recognition software we 
are using here is not yet part of 
Raspbian. We will therefore rely on 
a third-party repository from the 
Zamia-Speech project. 


PIGraspbherrype ~/eamiaspeech 


python3 va_eliza.py 


SPEECH 
WITH 


To set up the additional 
APT source, execute with root 
permissions (sudo -i): 


echo "deb http://goofy. 
Zamia.org/repo-ai/raspbian/ 
stretch/armhf/ ./" >/etc/apt/ 
sources. list.d/zamia-ai.list 

wget -qO - http://goofy. 
Zamia.org/repo-ai/raspbian/ 
stretch/armhf/bofh.asc | sudo 
apt-key add - 


With that in place, you can 
install the required packages using 
APT (again with root permissions): 


INFO: root:Generating grammar tables from /usr/lib/python3.5/lib2to3/Grammar.txt 
INFO: root:Generating grammar tables from /usr/lib/python3.5/lib2to3/PatternGrammar . txt 


Initializing... 


INFO: root:audio source: CM108 Audio Controller Analog Mono 


Please speak. (CTRL-C to exit) 
hello computer 

Hello there! 

switch on the lights 

OK, switching on the Lights. 
Switch on the radio 

OK, switching on the radio. 
computer 


Hello there! 


you are a computer 
Do you feel threatened by computers? 
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apt-get update 

apt-get install python3- 
nltools python-kaldiasr-doc 
kaldi-chain-zamia-speech-en 
pulseaudio-utils pulseaudio 


ASR on a WAV file 

We start out small: to try out the 
Kaldi-ASR speech-recognition 
engine, we will feed it a simple 
recording of a spoken sentence. We 
will use one of the example files that 
comes with it (or any other 16 kHz 
mono WAV file, for that matter): 


zcat /usr/share/doc/python- 
kaldiasr-doc/examples/dw961. 
Wav.gz > dw961.wav 


The code to run Kaldi ASR on 
this example is shown in the 
wav_decoder.py code. 


Live speech recognition 

The live_vad.py program is the 
foundation of our voice assistant: 
we record samples from our 
microphone using Pulse Recorder, 
feed it into a Voice Activity 
Detector (VAD), and decode it using 
Kaldi ASR. The MODELDIR variable 
points to the embedded English 
Zamia-Speech speech-recognition 
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Ideal for offline speech recognition, Zamia 
Speech offers pre-built Kaldi ASR packages 
for Raspbian, complete with pre-trained 

models for English and German. Everything 


model which we installed from 
their APT source earlier. You can 
experiment with different volume 
settings if you are not satisfied 
with the recognition results. 


Text to speech 

A voice assistant should 

not only recognise natural 
language, it should also be able 
to produce spoken answers to 
communicate back to the user. 
We will use eSpeak NG here for 
speech synthesis since it is free 
software and easy to set up. The 
espeakng_tts.py code is a short 
example of how to use it. 


Intents and actions 

We need to figure out what the user 
wants us to do: the user’s intent. 
We want to keep things simple 

for now So we will have just three 
intents: HELLO (say hello), LIGHTS, 
and RADIO (toggle the lights and 
the radio on or off). add_utt is 

a utility function that we use to 
create a Static mapping between 
natural language utterances 

such as ‘switch on the radio’ and 
corresponding intents. 
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With that in place, we can simply 
look up the user’s utterance to find 
the intent and generate a response. 
The va_simple.py code is our 
complete bot at this stage. 


Patterns and ELIZA 

To make our bot tolerant against 
input variations, we can use patterns: 
‘switch the (radio| music) (on|off)’ 


is free, cloudless, and open source 


CODE: 


LANGUAGE: 


DOWNLOAD: 


Taking it further 

There are endless possibilities to 
improve upon this voice assistant. 
You can get creative: make it 

tell jokes, say quotes from your 
favourite movies, or come up with 
your Own witty responses. Or 
make it more practical: add a wake 
word and attention mechanism, 
make it tell the current time 


There are endless 
possibilities to improve 
upon this voice assistant 


will already generate four patterns. 
Instead of a simple mapping between 
input and patterns, we will use their 
edit distance (the minimum set of 
insertion, deletion, and substitution 
operations to transform one into 
the other) to compute the closest 
match — this will make our bot 
tolerant against utterances we did 
not foresee. If we do not find a 

close enough match, we will turn 

to ELIZA to generate a response. 
The va_eliza.py code comprises the 
completed bot. 


or date; or, if you do not need 

it to run offline, add online 
skills like fetching the weather 
report or looking up definitions 
on Wikipedia. 

You can also improve its 
language capabilities: use more 
advanced speech synthesis 
tools like SVOX Pico or Google’s 
Tacotron for more natural- 
sounding responses, or go to 

to learn how 
to adapt the speech-recognition 
model to your domain. 
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MAKER: 
Al TYPE: 


Something you'd more 
traditionally associate with Al, 
this simulation creates artificial 
lifeforms in Python code, giving 
them different traits and allowing 
them to ‘breed’ and die and such. 
It would be quite horrifying an 
experiment if they were real, but 
they're not, so it's fine. Anyway, 
it's all displayed beautifully ona 
Unicorn HAT. 

As a bit of a bonus, Michael 
figured out a way to plug it into 
Minecraft Pi to get a different kind 
of visual representation of what 
goes on in the simulation. 


MAKER; 
Al TYPE: 


Like the name suggests, this 
project is used to count bees, 
specifically in a beehive. 
According to Mat on his blog 
about it, he couldn't find a decent 
enough, non-intrusive system to 
the trick. So he made one! 

It uses a standard Raspberry Pi 
Camera Module, and the Python 
code uses TensorFlow (and some 
manual training) to detect the 
bees in the image. Over time it's 
become a lot more accurate, 
through a mixture of machine 
learning and image optimisation. 


unt 


fna_of day 
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MAKER: 


POKEDEX | sine: 


There have been several Pokedex toys in the past 
20 or So years since the Pokemon games were 
released. However, none possessed the actual 
capability to use the image of a Pokemon to 
identify it like in the games and TV show. 

Using hundreds of images, from official artwork 
to renders and plushes and fan-works, Adrian 
managed to train a Raspberry Pi to be able to 
identify five of the 807 Pokemon currently in 
existence (minus different forms, regional variants, 
Mega evolutions, etc.). 

The results? From his blog about it, 


pretty accurate. Maybe Nintendo will huirtle:.98.62% (correct) 


license it and put it in Pokemon GO? 


INTELLIGENT “" 
DOORLOCK °.:,.. 


raspberrypi.org/magpi 


DRONE 
OBJECT 
DETECTION 


feature 


MAKER: 
Al TYPE: 


Drone technology, and 

drone automation, is always 
improving. Pairing drones with 
image recognition seems like 
a no-brainer, and this fusion 
of technology has been used 
in Africa to monitor house 
construction projects. 

The images capture the various 
building stages of the houses in an 
attempt to make sure that if any 
problems arise, the team will know 
about it. Using nearly 1500 images, 
they trained the Al to expertly look 
out for the signs of different parts 
of house construction so it could 
be relayed back for inspection. 
This project was created with the 
NanoNets API ( ). 


This project is pretty complex, 
but basically it’s a smart lock. 

All you need to do is train it to 
recognise people you know and if 
they come to your door, it will let 
you know who is there. It's more 
complicated than just installing a 
camera you can stream over the 
web, but it means you can receive 
a text message about who it is 
rather than squint at a camera 
from across town. 

This particular project uses 
Alexa, and it can also open the 
door without you being physically 
present. It will even welcome your 
guest. Proper Star Trek stuff. 
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Projects SHOWCASE 


DETECTOR 


Equipped with all manner of sensors, this Ghost Detector is designed 
to discover paranormal presences. A spooked Phil King investigates 


Quick 
Facts 


he truth is out there... his father. “My dad watches alotof Raspberry Pi offers an infrared 

> Build details At least that’s what they paranormal investigation shows,” camera,” recalls Anthony, “so I 
are at used to say on The X-Files. says Anthony, “so I thought it decided to build something that 
soon Well, if there is any paranormal would be a fun project to give could record video with overlaid 

activity around, Anthony DiPilato’s as aChristmas gift.” sensor data.” 

: cae. - sensor-packed Ghost Detector The Raspberry Pi records video, 
magpl.cc/ aims to find it. While he built the Infrared camera audio, and sensor data, then saves 
zbDYrV device around two years ago, this While the project started off as it to a USB flash drive. Mounted 

> The ‘wooden’ top-secret project has only just a simple Arduino-based EMF on top of the device, an official 
ace = been shared with the wider world. (electromagnetic field) meter, it Raspberry Pi 7-inch touchscreen 
nite The idea stemmed from a desire quickly evolved into something provides a user interface, while 

to create ahome-made present for far more ambitious. “I saw also displaying the data from the 


> The project 
took two 
months 


to build A7-inch touchscreen shows 


. The detector the live camera view overlaid 


includes a 
coolingfan = — 


with sensor data 


Aided by two sets of IR LEDs, 
an infrared camera captures 


images in the dark 


Twin antennas amplify the 
signal for the EMF sensors 
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BUILD A GHOST DETECTOR 


>STEP-01 


numerous sensors and a live video 


view from the infrared camera. 
Featuring a pistol-grip handle, 
the body of the detector was 
3D-printed on Anthony’s newly 
acquired Monoprice Maker Select. 
He designed the enclosure using 


Since it 1s a pseudoscientific 
instrument, I wanted to make 
it look as ridiculous as possible 


the Autodesk Fusion 360 CAD 
software, which offers a free 
licence for hobbyists. 

“Since it is a pseudoscientific 
instrument, I wanted to make it 
look as ridiculous as possible,” 
he tells us. “So I included rabbit- 
ear telescopic antennas [for 
the EMF sensors] and a Geiger 
tube. I thought the stained 
wood enclosure would match 
that aesthetic.” 


Sensory overload 
Continuing the theme of making 
it as ludicrous as possible, 
Anthony crammed the detector 
with “as many sensors as | 

could fit.” Along with the EMF 
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>STEP-02 


sensors, there’s a magnetometer 
(compass), altimeter, temperature 
and barometric pressure sensor, 
microphone, and a Geiger counter 
to measure radioactivity. Most of 
the sensors and other electronics 
are mounted on stripboard, 


including two 5 V 3A step-up power 
supplies, an Arduino Nano, anda 
logic level converter to interface 
the Nano to the Raspberry P1. 

The Geiger counter is a separate 
board, while its Geiger tube is 
mounted on the front along with 
the camera and two lots of infrared 
LEDs either side. To power the 
device, two Panasonic 18650 
3400 mAh batteries are housed in 
the handle. 

From start to finish, the Ghost 
Detector took Anthony around two 
months to build: “The only major 
issue | encountered was the control 
board for my 3D printer burned 
out, and needed to be replaced 
before I could finish the project.” 


GHOST DETECTOR 


>STEP-03 


Projects 


It took him a mere two days to 
program the software, mainly 
comprising Python scripts. 
Asked if he has detected any 
unearthly presences, Anthony 
replies, “I only tested at a few 


local places that are supposedly 


haunted, but I was not able to 


record any conclusive evidence 


of hauntings.” He did discover 


that blood absorbs infrared light, 
however, showing up all the veins 
in his arm on the camera view — 


which looks pretty spooky. 


Above Anthony 
tested the 
electronics out 
before cramming 
them into the 
3D-printed 
enclosure 
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Amechanical switch is 
pressed whenever the lid 


is opened by a squirrel 


The nuts are visible 


behind a glass panel 
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> It correctly 
predicted the 
cold winter of 
2017-18 


» Carsten plans 
to adda scale 
to weigh 
the nuts... 


> ..for more 
accurate 
measuring 
of nut 
consumption 


» Raccoons have 
broken into 
the feeder 


>» Avideo 
‘security 
camera’ now 
monitors 
all visitors 


Predict the weather with... squirrels and nuts! ? 
Nicola King lifts the lid on an ingenious project 


ack in 2012, Carsten 

Dannat was at a science 

Summit in London, during 
which a lecture inspired him to 
come up with a way of finding 
correlations between nature and 
climate. “Some people say it’s 
possible to predict changes in 
weather by looking at the way 
certain animals behave,” he tells 
us. “Perhaps you can predict 
how cold it’ll be next winter by 
analysing the eating habits of 
animals? Do animals eat more 
to get additional fat and excess 
weight to be prepared for the 
upcoming winter?” 

An interesting idea, and one 

that Germany-based Carsten was 
determined to investigate further. 
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“On Teturning home, | got the 
sudden inspiration to measure the 
nut consumption of squirrels at 
our squirrel feeder”, he says. Four 
years later and his first prototype 
of the ‘The Squirrel Cafe’ was 
built, incorporating a first- 
generation Raspberry Pi. 


A tough nut to crack 

A switch in the feeder’s lid is 
triggered every time a squirrel 
opens it. To give visual feedback 
on how often the lid has been 
CMAMAG, 21 SS — Se sinaveinit IL. aD. 
display shows the number of 
openings per meal break. A USB 
webcam is also used to capture 
images of the squirrels, which are 
tweeted automatically, along with 


A Raspberry Pi is 
connected to the switch, 
LED display, and a USB 
webcam to take photos 


stats on the nuts eaten and time 
taken. Unsurprisingly perhaps, 
Carsten says that the squirrels 
are “focussed on nuts and are 
not showing interest at all in 


|» 


tie cleeimonites 
So, how do you know how many 
nuts have actually been eaten by 
the squirrels? Carsten explains 
that “the number of nuts eaten 
per visit is calculated by counting 
lid openings. This part of the 
source code had been reworked 
a couple of times to get adjusted 
to the squirrel’s behaviour while 
erabbing a nut out of the feeder. 
Not always has a nut been taken 
out of the feeder, even if the 
lid has been opened.” Carsten 
makes an assumption that if 
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the lid hasn’t been opened for 

at least 90 seconds, the squirrel 
went away. “I’m planning to 
improve the current design by 
implementing a scale to weigh 
the nuts themselves to get a more 
accurate measurement of nut 
consumption,” he says. 


Just nuts about 

the weather! 

The big question of course is 
what does this all tell us about 
the weather? Well, this is a 
complicated area too, as Carsten 


Some people say it’s possible to predict changes 1n 
weather by looking at the way certain animals behave 


illustrates: “There are a lot of 
factors to consider if you want 

to find a correlation between 
eating habits and the prediction 
of the upcoming winter weather. 
One of them is that I cannot 
differentiate between individual 
squirrels currently [in order to 
calculate overall nut consumption 
per squirrel].” 

He suggests that one way 
around this might be to weigh 
the individual squirrels in 
order to know exactly who is 


a, 
mr 
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>STEP-O1 
Lid switch 


When a squirrel opens the lid, a 


Wie 
. \ ae 


mechanical switch is triggered. This 
replaced a magnetic reed switch, which 
Carsten says wasn't totally reliable. 
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ft A squirrel 
enjoying a tasty 
treat at the 
Squirrel Cafe 


visiting the Cafe, with what he 
intriguingly calls “individual 
squirrel recognition” — a planned 
improvement for a future 
incarnation of The Squirrel Cafe. 
Fine-tuning of the system 
aside, Carsten’s forecast for the 
winter of 2017/18 was spot-on 
when he predicted, via Twitter, 
a very cold winter compared to 
the previous year. He was proven 
right, as Germany experienced 
its coldest winter since 2012. 
Go squirrels! 


The 
results of a 
raccoon’s 
rampage 


UL 
PUTreT 


>STEP-02 
Nut supply 


The feeder is filled with peanuts. Since 
these are split into halves, it’s assumed 
that each lid opening results in half a nut 
being consumed by the squirrel. 


The Squirrel Cafe GT heSquirreiGate - Jun 22 
Squirrel chowed down on 3.5 nuts for 3.43 min at 17:38:08 CEST. An #loT | 
project to predict how cold i'll be next winter. #ThingSpeak 


>STEP-03 

Tweepy tweet 

After each meal visit, the Tweepy 
Python library is used to automatically 
tweet the details and a photo taken by 
a connected USB webcam. 
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GLOCKENSPIEL 


This project strikes a chord for its clever use of Sonic Pi 
and LEGO to make sweet music, as David Crookes discovers 


obots have already blown Raspberry Pi playing a glockenspiel Sonic Pi-controlled glockenspiel 
> It uses Sonic Pi their own trumpet: Toyota andit’s been music to our ears. after seeing similar projects online 
version 3.0.1 developed a humanoid It’s all thanks to Robin Newman _ that used an Arduino. 
> LEGO forms in 2004 which could play When whose love of computers and “Version 3.1 was a game changer 
the Pi- You Wish Upon a Star by clasping music goes way back. Inthe1980s, — because it allowed Sonic Pi to 
heats the instrument in its hands and he networked 24 BBC Micros and communicate with the outside 
blowing air through its mouth. had them play parts of a Bach world using either MIDI signals or 
dain ‘ie Since then, we’ve seen robots play |§ Brandenburg Concerto. “Today, Open Sound Control messages,” 
centre of notes the drums and guitar; even going 80 percent of my work with he explains. “It enables Sonic Pi to 
is 24mm as far as recording an album. But Raspberry Pi boards involves Sonic interact with Python-controlled 
Siccsctcuccm mow we've heard the results of a Pi,” he says. He got the idea for a devices and to interact easily with 


used is :C6 ote ie 


‘ PTA E Ce re a a er eabhant a tied So 5 Bie oe ert aN ar PCR aCe te ye 
. ; . >. “i ast ~ : . ‘ 7 “a wt A Be 7 _ Sy > ed ae ae a at a 
to :E7 ; i BRL at a se MT Pl et” . weet On AEE SR ane at Ren yh ag a Mh 


PEON ae aod wae ne tea em 
SD hed pote se RI PS ae Sah io te et Es 
>? Le oe wee FS it te 
mrss Meat og SRD aes Daten bel rok 
atin > a : 


cat S92 


» Robin's You can pick up glockenspiels on eBay 
glockenspiel and it’s also possible to buy eight-note 
was vintage children's toys, although Robin says 
Cold War East some may have “dubious tuning” 
Germany 
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The project uses a Raspberry Pi 3 fitted . - = = 3 
with a RaspPiO Pro Hat that can easily = © 
accommodate 11 circuits > Sa ~ueesiniaae 
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The LEGO hammers use a 15 beam 
with a 5x3 angle on the end, pivoted o 
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on an axle of length three 
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>STEP-01 


signals to and from the Pi’s GPIO 
pins. I wanted to use the fact that 
it could control a glockenspiel 
and play itself at the same time to 
accompany the instrument.” 


Setting up 

Robin already had a glockenspiel. 
A 30-year-old gift to his son, it was 
languishing in his attic. As such, 


SONIC Pi GLOCKENSPIEL 


>STEP-02 


off. This worked fine and so the 
question was how could this small 
movement be used to hit the keys.” 
It was then that he turned to LEGO. 


Hammer time 

Before the Pi was launched, Robin 
had spent a few years working 
with the LEGO EV3 system, mainly 
producing colour-sorting robots. 


80 percent of my work 
with Raspberry Pi boards 


involves Sonic P1 


he sought to produce an easily 
constructed project that could be 
added to the instrument. The Pi, he 
envisaged, would control hammers 
to strike the glockenspiel’s 
metal bars and he decided to use 
solenoids as the actuators. 

“T bought a5V, Adafruit- 
sourced solenoid and I already 
had a suitable power supply to 
hand,” he recalls. “I also hada 
power transistor and projection 
diode from an Arduino starter kit. 
I was able to connect them up to 
a GPIO pin and use the GPIO Zero 
LED command to switch it on and 
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“After some experimentation, it 
turned out to be beautifully simple 
to produce a hammer mechanism 
out of LEGO which could then be 
driven by the solenoid, providing 
just the right kick,” he says. To do 
this, he had the LEGO hammers 
strike the notes from underneath, 
allowing gravity to return them 

to their resting position. “It’s 
important that the hammers strike 
the notes and then immediately 
move away from them so that 
they don’t dampen the sound,” 

Inve oqgolke as, |FieGucm Wasim Cin, (6 Ve 
software could work its magic. 


>STEP-03 


Robin wrote a Python script to 
drive the GPIO pins and therefore 
the solenoids, and he delayed the 
notes sent to the glockenspiel by 
0.3 seconds. This compensated 
for the delay between the Sonic 
Pi playing a note and the note 
sounding in a speaker, allowing the 
Pi to accompany the glockenspiel 
without it sounding odd. 

“Tm now looking at a system 
of overhead hammers,” Robin 
reveals, keen to continue refining 
the project. “This will open up the 
range of glockenspiels that can 
be used.” 


Projects 


Below Robin 

has been 
experimenting 
with overhead 
hammers, winding 
38cm of insulated 
1/0.6 wire around 
a biro to form 


a weak spring, 
allowing them to 
return toa rest 
position clear of 
the metal notes 
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Projects 


>» Nemo-Pi has 


been tested to 
a depth of up 
to 50m 


> The first 
Nemo-Pi has 
been running 


for a year 


>» Each Nemo-Pi 


setup costs 
$600 max 


> The price 


depends on 
the number 
of sensors 


» Eight sensors 


34 


are currently 
being tested 


NEMO- 


Coral reefs are threatened by divers and climate change, but one 
organisation hopes to save them by using a Raspberry Pi as an 
underwater ‘weather station’. David Crookes reports 


or the past two years, the 

Save Nemo Foundation 

has worked hard to protect 
coral reefs off the coast of Thailand 
and Indonesia. Its members have 
been sinking concrete blocks 
next to the reefs, allowing diving 
and snorkelling boats to safely 
moor by using them as anchor 
points. In doing so, they’ve 
eased the problem of boat crews 
dropping anchor directly into the 
reefs, which has already caused 
significant damage. 


A waterproof 10 W solar panel is 
controlled by this WittyPi Mini RTC 
and power management module 


But while that has had a positive 
effect on the creeping destruction, 
the organisation spotted another 
opportunity. “We realised we 
could do more by making these 
moorings smart,” says its CEO 
Diemo Niemann. “So we created 
a plan to collect underwater 
physical and chemical data that 
is not only essential for science, 
but helpful for local people and 
their business.” The result? 
Nemo-Pi, a device able to measure 
temperature, visibility, pH levels, 


The Pi can be powered each day for 90 minutes - enough 
for 15 daily measurements to the server. New GSM/GPRS 
modules consuming under 2Ah of power are being tested 
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and the concentration of CO, and 
nitrogen oxide at each anchor point. 


Oh buoy 


Every one of the concrete moorings 
has a buoy attached on top and, 

as it bobs in the water, it shows 
boat crews where they can anchor. 
The idea behind Nemo-Pi is to put 
an encased Raspberry Pi into the 
buoy, attach it to a solar panel for 
power, include a GPS device so that 
its location can be determined, 

and run an array of sensors from 


Housed within a saltwater- 
resistant buoy, It’s important that 
the Pi has sufficient power to 
collect and send data 


raspberrypi.org/magpl 


The Nemo-Pi project, which won a Google Impact Challenge 2018 award, 
needs volunteer programmers. Interested? Email nemopi@save-nemo.org 


the computer into the sea that can 
then feed back vital information. 

A team of programmers has been 
busy coding in Python and C++ on 
a Slimmed Debian environment 
to create the Nemo-P1 itself. 
Meanwhile, much testing has been 
carried out to ensure the project 
is saltwater resistant and able 
to withstand high levels of UV 
irradiation. It is important that the 


Although the project is still in 
a pre-production stage (“we have 
eight sensors under long-term 
alpha and beta testing,” says 
Diemo), the setup works well ona 
number of levels. Since it allows 
water conditions to be monitored, 
holidaymakers — as well as 
underwater, hotel, and cruising 
businesses — can determine 
whether it’s worth making a trip. 


We created a plan to collect 
underwater physical and 


chemical data 


entire setup is simple, sustainable, 
affordable and reliable, not to 
mention energy-efficient. 


Saving energy 

“The Nemo-Pi has a modified real- 
time clock and GPRS/GPS hub,” 
Diemo explains. “With this, the 
device is powered up and down to 
Save energy and send its data direct 
to our server, which takes care of 
the visualisation and processing. 
During the night, Nemo-Pi is 
automatically powered off and we 
have developed a library to optimise 
data transmission against sunlight, 
power consumption and battery 
load. It means a Pican operate 
endlessly — or at least until the 
battery or solar gives up.” 
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“Hundreds of dives and 
snorkelling trips have been 
cancelled each day while out on the 
water because of bad conditions,” 
Diemo continues. “If you know 
WN te WO [ie eh! UNS elane ame. 
you can Save gasoline, working 
hours, and unnecessary anchoring, 
and because of that we can help 
generate corals and sea life.” 

Nemo-Pi also assists scientists, 
universities, and governments 
by picking up on signs of climate 
change and dangers to marine 
wildlife. “It is a small but 
important step against global 
warming and pollution of the 
sea and it all helps to make 
our ocean more blue again,” 
Diemo concludes. 


NEMO-PI 


MONITORING 
THE SEAS 


Projects 


>STEP-02 


Nemo- Pi . 


Config CUm ap 


Location cs: 


Station TOS 
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>STEP-03 
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Find and manage files and folders on your Raspberry Pi and connected servers 
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Spreurty rerrete fokder bo coer! 


Tutorial DY Wartuc: 


Knitting Nancy 


Conducting 
thread - 
smooth 


Wool or other 
thread 


Reel holder 


A/D converter, 
either 
commercial 
based on the 
MCP3008 or as 
we made in The 
MagPi #68 


2 x Crocodile 
clips 


270 Q resistor 


Crochet hook, 
snipe-nose 
tweezers, 
darning needle 
(optional) 


Fibres under 
Compression 


High 


resistance 


Figure 1 A representatio 
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Fibres under 
Tension 


Low 
resistance 


_ MIKE COOK 


Veteran magazine author from the old 
_ days and writer of the Body Build series. 
Co-author of Raspberry Pi for Dummies, 


Raspberry Pi Projects, and Raspberry Pi 
Projects for Dummies. 
magpi.cc /259aT3X 


Make a Stretch Armstrong out of code and some thread 


nitially it seems improbable that you could 
knit your own sensor, but you can. With the 
right sort of knitting and some conductive 
thread, you can make a stretch sensor quite simply. 
There is a touch more of the experimental nature 
about this project than most of the ones we do, but 
it is none the less rewarding for that. Here at the 
Bakery we are old enough to have been brought up 
in a time when everyone was taught needlework at 
primary school, but unfortunately this seems no 
longer to be the case. We are quite firm believers 

in the opinion that there is no such thing as 
gender-specific activities. 


Knitting Nancy 

A Knitting Nancy can be made from an old wooden 
cotton reel and four very small nails, but for not 
very much more you can purchase a fancy one. 
These are often built in the form of a cartoon-like 
figure. Their purpose is to produce ‘French knitting’, 
which is tubular. Due to the way the thread is looped 
back on itself, it acquires a sort of springiness. By 
incorporating a conducting thread along with the 
basic thread, we can make a sensor that changes its 
resistance as it is stretched. 


How it works 

Conductive thread is made from tiny slivers of 
Stainless steel foil, spun together to make a thread. 
We used the smooth variety for these experiments; 
this type is not so ‘hairy’ as the normal type, but 
there is nothing to stop you using that. 

Stainless steel is not the best electrical conductor, 
but it is good enough when used to stitch circuit 
paths over a short distance; this is because when 
you stitch with it, the thread is under tension. This 
means that the short foil pieces make good contact 
with others that surround it. However, when the 
thread is not under tension, and even more when 
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Tutorial 


Knitting Nancy 


Stretch Armstrong display 


A/D converter 


Fr 
Reading Resistance 
163 sQ 


: 


-~* -~* 
* 
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Stretch sensor 


>STEP-O1 
Making a bobbin holder 


Ona1i50mm by 90mm piece 
of wood (actually a floorboard 
off-cut) we drilled three 6mm 
holes part way through and 
glued in three 6mm diameter 
80mm long dowels. A piece 
of 2mm foam was glued to 
the underside to ensure a firm 
grip on the table and also to 
prevent it scratching the table. 


Tutorial 


Vin (3V3) it is under a slight compression, the thread’s fibres 
bunch up and tend to not make contact over their 
whole length. This leads to an increase in resistance 
of the thread. This effect is illustrated in Figure 1. 
The result is that as the knitted tube is stretched, its 

R1 resistance drops. 

Total Current | 270R Details of how to knit your own sensor are shown 
in the numbered steps. We got a resistance range of 
about 140 between the stretched and unstretched 
sensor; this was for tube lengths of about 24cm. 

To A/D There are many videos on French knitting on the 
internet. One of the first we found (magpi.cc/frZJnV) 
shows you how to cast on and off. 


Rs Vout Reading the resistance 

Voltage Reading The stretch sensor is connected to an input channel 
of an A/D converter using crocodile clips, which 
are known in the US as alligator clips. In the Drum 
Sequencer project of The Mag Pi #68, we showed 
you how to make an A/D converter. Figure 2 shows 
you not only how to connect this up, but also the 
formula needed to calculate the resistance of the 
sensor. We can find the resistance of the sensor 
if we know the voltage across it, and divide that 


Stretch Sensor 


by th h h it. This is called 
Total Current | = 3.3 / (R1 + Rs) a. he 
Voltage across RS = | xX RS We have a resistor, R1, of 270 Q connected 


between the 3V3 supply and the analogue input, 
with the sensor wired between the analogue input 
Rs = R1X 1 and ground. Resistors in series simply add up to 


Vin | 
Vout 


Calculating and measuring the sensor resistance 


>STEP-02 
Start knitting 


The initial setup of the threads 
is shown in the photo. We 
started knitting a few rounds 
with a base thread before 
laying the conducting thread 
beside it. You then have to Lift 
the two threads over the hooks 
together. Occasional gentle 
tugs on the thread out of base 
stops the threads bunching 
up. Be careful not to make 

the tension too tight, as it will 
make lifting the threads too 
difficult and you could snap 


the conducting thread. | Physical wiring attaching the resistor and sensor 
to the A/D converter 


>STEP-03 
Making a stitch 


4 


give the total resistance, so we can calculate the 
total current. And knowing this value of current, 
we can measure the voltage across the sensor. 
Unfortunately, these formulae require you to know 
the resistance of the sensor, which is what we are 
trying to measure. Fortunately, it is just a simple 
simultaneous equation problem that can be solved 
by the substitution method. 


Resistors in series simply add 
up to give the total resistance, 
So we can calculate the total 


Finally, you can manipulate the resulting equation Figure 4 
so that Rs is the subject of the equation. We will leave Ne aes 
this as an exercise to the reader to verify the final 
formula. Figure 3 shows the physical wiring of the 
sensor to the A/D converter, with R1 being connected 
to 3V3 and Ao, and the sensor's connection wires to 
eround and Ao. 


Stretch Armstrong 

Stretch Armstrong was a doll that could be stretched 
to avery large extent and then recover. This was 
about 40 years ago, but it made a reappearance a few 
years back. We are going to do a software version 

of this, and you can use an image of your favourite 
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Tutorial 


>STEP-04 
Casting off 


>STEP-05 
Mixing the threads 
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WALKTHROUGH 


Armstrong; we chose Alexander Armstrong from 
Pointless, and created an image 300 pixels high by 96 
wide, with a transparent background, and placed it in 
a folder called images. Alongside this we put the code 
shown in the stretch. py listing. 

This Python 3 program is written under the 
Pygame framework, and is quite simple. The Vin 
and R1 variable values are defined at the start of the 
program. The code shows the standard values — but, 
for more accuracy, you can use measured values. The 
calculation of the sensor’s resistance is done in the 
readSensor function, and acouple of if statements 
stop the code from trying to divide by zero. The 
drawScreen function actually does the rescaling of 
the image and works out where to put the head so the 
feet always stay in the same place. The Q (ohm) and 
co (infinity) symbols are printed using their Unicode 
character numbers (0x3a9 and 0x221E). The results 
of two different stretch measurements are shown 
in Figure 4. 


Taking it further 

While Stretch Armstrong is a simple example of the 
use of the sensor, there are many others. One that 
Springs to mind is to use several sensors to control an 
on-screen virtual puppet, or even a servo-controlled 
real puppet. It could be used to control effects in 

a MIDI sound setup, or even used to weigh things. 
You can do this by attaching the sensor to a piece 

of bungee elastic so that it takes a lot more force to 
stretch it. Note that for most applications you don't 
have to calculate the resistance, just use the raw 
A/D readings. 
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stretch.py 


01. 
02. 
03. 
04. 
05. 
06. 
07. 
08. 
09. 


10. 


11. 
12. 


13. 
14. 
15. 


16. 
17, 
18. 
19. 
20. 
21. 
22. 
23. 
24. 
25. 
26. 
27. 
28. 
29. 
30. 


31. 


32. 
33. 
34. 


35. 
36. 


37. 
38. 
39. 


40. 
41. 
42. 
43. 
44. 


KNIT YOUR OWN STRETCH SENSOR 


import pygame, os, time, random 
import spidev 


pygame.init() # initialise graphics interface 


os.environ[ 'SDL_VIDEO WINDOW _POS'] = ‘center' 
pygame.display.set_caption("Stretch") 
pygame.event.set allowed(None) 

pygame.event.set allowed([pygame.KEYDOWN, 
pygame.QUIT | ) 

textHeight=26 ; font = pygame.font.Font(None, 
textHeight ) 

ScreenWidth = 206 ; screenHeight = 500 

screen = pygame.display.set mode([screenwWidth, 
screenHeight | ,2, 32) 

background = (150,100,400) ; pramCol = (180,200,150) 
lastReading = 0.9 3 reading = 200 

Vin = 3.3 3 R1 = 270 # or replace with measured 
values 


def main(): 

global lastReading, reading 

loadResource( ) 

initScreen() 

while(1): 
checkForEvent() 
readSensor() 
if lastReading != reading: 

drawScreen() 

lastReading = reading 
time.sleep(@.1) 


def drawScreen(): 
pygame.draw.rect (screen, background, (8,474, 

screenWidth, screenHeight) , 2) 
pygame.draw.rect (screen, background, (0,28, 

screenwWidth, 450) ,0) 
drawwords(str(reading) , 40,478, pramCol, background) 
if reading > 600: 


drawWords(chr(0x221E) ,116,478, pramCol, 
background) # infinity 
else: 
drawWords(str(Rs)+" "+chr(@x3a9) ,116,478, 
pramCol , background) 


Stretch = 500 - reading 
if stretch > 2 : 
stretched = pygame.transform.smoothscale( 
armstrong , (96,stretch) ) 
screen.blit(stretched, (54,450 - stretch) ) 
pygame.display.update() 


def drawWords(words,x,y,col,backCol) : 
textSurface = font.render(words, True, col, 
backCol) 
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45. 


46. 
47. 
48. 


49. 
50. 
51. 


52. 


23. 
54. 
25. 
56. 
57. 
58. 
59. 


60. 
61. 
62. 
63. 


64. 


65. 
66. 


67. 
68. 
69. 
70. 
71, 
72, 
73. 
74. 
75. 
76. 
77. 
78. 
79. 
80. 
81. 
82. 
83. 
84. 
85. 
86. 
87. 
88. 
89. 
90. 


>PYTHON 3 


DOWNLOAD: 
magpi.cc/1NqJjmV 


textRect = 
textSurface.get_rect() 

textRect.left = x 

textRect.top = y 

screen.blit(textSurface, 
textRect) 


PROJECT 
VIDEOS 


Check out Mike's 
Bakery videos at: 
magpi.cc/DsjbZK 


def initScreen(): 
pygame.draw.rect(screen,ba 
ckground, (8,8, screenWidth, screenHeight) , 0) 
drawWords("Reading Resistance",16,454,pramCol, 
background) 


def loadResource(): 

global spi, armstrong 

Spi = spidev.SpiDev() 

spi.open(0,0) 

Spi.max_speed hz=1000000 

armstrong = pygame. image. load( 
"images/Armstrong.png").convert_alpha() 


def readSensor(): 

global reading,Rs 

adc = spi.xfer2([1,(8)<<4,0]) # request 
channel 

reading = (adc[1] & 3)<<8 | adc[2] # join two 
bytes together 

if reading !=0: 


Rs = R1*( ( 1/ (Vin / (reading * Vin /1024) 
=e) 
Rs = int(Rs) # convert into interger 
else: 
Rs = @ 


def terminate(): # close down the program 
print ("Closing down") 
pygame.quit() # close pygame 
os. exit(1) 
def checkForEvent(): # handle events 
global reading 
event = pygame.event.poll() 
if event.type == pygame.QUIT : 
terminate() 
if event.type == pygame.KEYDOWN : 
if event.key == pygame.K ESCAPE : 
terminate() 
if event.key == pygame.K_d 
os.system("scrot -u" 


: # screen dump 


# Main program logic: 
if _name_ == ° 
main() 


5. 'maane fee 
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MARK VANSTONE 


Educational software author from the 
nineties, author of the ArcVenture series, 
disappeared into the corporate software 
wasteland. Rescued by the Raspberry Pi! 
technovisualeducation.co.uk 
twitter.com/mindexplorers 


Press Play to Start 


Instructions are displayed here 
' The game has four coloured 
Brian - 


= buttons that light up when 
A they are pressed 


Let's get this Brian 
battle underway 


PYGAME ZERO 


VIDEO GAME LOGIC WITH 


Recreate a classic electronic game using Pygame Zero 


ong, long ago, before the Raspberry Pi Figure 1 does not run straight from IDLE then you 
existed, there was a game. It was a round may need to upgrade Raspbian on your Pi. 

plastic box with four coloured buttons on 

eee § top and you had to copy what it did. To reconstruct 


or newer : ; ; ; ] 
this classic game using Pygame Zero, we’|l first figure Py 
> An image 
01 


need a name. To avoid any possible trademark 
manipulation 


program such misunderstandings and because we are using the import pgzrun 
as GIMP, or Python language, let’s call it ‘Brian’. The way the Q2. 
nego OTN game works is that Brian will show you a colour Q@3. # Your program code will go here 
magpi.cc/keaiKi 
sequence by lighting up the buttons and then you Q4. 
ee have to copy the sequence by pressing the coloured Q@5. pgzrun.go() 


version of 
Merucyekeeay  Duttons in the same sequence. Each round, an extra 


button is added to the sequence and you get a point 
for each round you complete correctly. The game 
continues until you get the sequence wrong. 


With Pygame Zero V1.2 you can now run your program 
from IDLE with these extra lines top and bottom 


> Agood memory 


The stage is set 
If we are using Pygame Zero, the point is to get things 


Run, run as fast as you can happening quickly, so let’s get some stuff on the screen. 
In the first part of this series (magpi.cc/71), we We are going to need some images that make up the 

ran our Pygame Zero code by typing the pgzrun buttons of the Brian game. You can make your own or 
command into a Terminal window, as previously you can get ours from GitHub at magpi.cc/keaiKi. The 
there was no way of running a Pygame Zero program images will need to be in an images directory next to 
directly from IDLE. With the 1.2 update of Pygame your program file. We have called our starting images 
Zero, there is now a way to run your programs redunlit, greenunlit, blueunlit, and yellowunlit because 
directly from IDLE without using a Terminal window. all the buttons will be unlit at the start of the game. We 
You will need to make sure that you are running have also got a play button so that the player can click on 
version 1.2 or later of Pygame Zero. If the code in it to start the game. 
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topleft midtop topright 


center 


midlett midright 


bottomleft midbottom bottomright 


Above There are nine positions that an Actor's co-ordinates 
can be aligned to when the Actor is created 


>STEP 03 

Getting the actors on stage 

AS we Saw in part one, we can create Actors by 
simply supplying an image name and a position 
on the screen for it to go. There are several ways 
of supplying the position information. This time 
we are going to use position handles to define 
where the character appears. We will use the same 


co-ordinates for each quadrant of the whole graphic, 


but we will change the handle names we use. For 
these Actors we can use bottomright, bottomleft, 
topright, and topleft, as well as the co-ordinates 
(400,270), which is the centre point of our whole 
eraphic. Have a look at Figure 2 and see how this 

is written. 


>STEP 04 

Look at the state of that 

We now need to add some logic to determine if 
each button is on or off and show it lit or unlit 
accordingly. We can do this by adding a variable 

to each of our Actors. We want it to be either on or 
off, so we can set this variable as a Boolean value, 
i.e. True or False. If we call this variable ‘state’, 
we can add it to the Actor by writing (for the first 
button): myButtons[@].state = False. We 
then do the same for each of the button Actors with 
their list numbers 1, 2, and 3 because we defined 
them as a list. 


>STEP 05 

Light goes on, light goes off 

We have defined a state for each of our buttons, 
but now we have to write some code to react to 

that state. First let’s make a couple of lists which 
hold the names of the images we will use for 

the two states. The first list will be the images 

we use for the buttons being lit, which would 

be: buttonsLit = ['redlit', ‘greenlit', 
‘bluelit', ‘yellowlit']. We then need alist of 
the unlit buttons: buttonsUnlit = ['redunlit', 
‘greenunlit', ‘blueunlit', ‘yellowunlit' ]. 
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01. 
O25 
Us, 
04. 


OS. 


06. 
O07. 
08. 
Us: 
10). 
ie 
2. 
13. 
14. 
S5 


figures Py 


>PYTHON 


DOWNLOAD: 
magpi.cc/hPLasi 


import pgzrun 


myButtons = [ | 
myButtons.append(Actor('redunlit', 
bottomright=(40@, 27@))) 
myButtons.append(Actor('greenunlit', 
bottomleft=(40@, 270) )) 
myButtons.append(Actor('blueunlit' , topright=(400,27@) )) 
myButtons.append(Actor('yellowunlit' , topleft=(400, 270) )) 
playButton = Actor('play', pos=(400,54@)) 


def draw(): # Pygame Zero draw function 
screen. fill1((30, 10, 30)) 
for b in myButtons: b.draw() 


playButton.draw() 

Figure 2 Set up the screen by 
creating Actors and draw them 
in the draw() function 


pgzrun.go() 


Figure 3 Adding a state to 
the buttons means that we 
can change the image in our 
update() function and draw 
them as Lit 


import pgzrun 
myButtons = [ | 
myButtons.append(Actor('redunlit', 
bottomright=(400, 27@) )) 

myButtons[@].state = False 
myButtons.append(Actor('greenunlit', 

bottomleft=(400, 270))) 

myButtons[1].state = False 
myButtons.append(Actor('blueunlit' , topright=(400,27@) )) 
myButtons[2].state = False 
myButtons.append(Actor('yellowunlit' , topleft=(400,270))) 
myButtons[3].state = False 
buttonsLit = ['redlit', ‘greenlit', 
‘yellowlit' | 

buttonsUnlit = ['redunlit', 
"yellowunlit' ] 

playButton = Actor('play', pos=(400,54@)) 


‘bluelit’, 


‘greenunlit', ‘blueunlit', 


def draw(): # Pygame Zero draw function 
screen. fill((30, 10, 30)) 
for b in myButtons: b.draw() 
playButton.draw() 


def update(): 
bcount = @ 
for b in myButtons: 
if b.state == True: b.image = buttonsLit[bcount | 
else: b.image = buttonsUnlit[bcount ] 
bcount += 1 


# Pygame Zero update function 


pgzrun.go() 
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GLOBALS 


You can 
read global 


variables 
inside a 
function, but 
if you change 
the value of 
the variable, 
you must 
declare it 

as global in 
the function. 


figure py 


Then we can use these lists in an update() function 
to set the image of each button to match its state. 
See Figure 3 to see how we can do this. 


>STEP 06 

Switching images 

We can see from Figure 3 that each time our 
update() function runs, we will loop through our 
button list. If the button’s state is True, we set the 
image of the button to the image in the buttonsLit 
list. If not (i.e. the state variable is False) then 

we set the image of the button to the image in the 
buttonsUn1it list. At this stage you can test to see 
if your logic is working by setting the state variables 
at the top of the code to True and see if when you run 
the program, the buttons display lit. 


>STEP 07 

What happens if | press this button? 

The idea of a button is that you can press it and 
something happens, so the next thing we need to write 
is a way to allow the user to press the buttons and make 
them light up. We can do this with the Pygame Zero 
functions on_mouse_down() and on_mouse_up(). 
What we need to test in these functions is if the mouse 
has been clicked down, if it has, we should set our 
button state to True. We also need to test if the mouse 
button has been released, in which case, all the buttons 
should be set to False. We can test the value we are 
passed (pos) into these functions with the method 
collidepoint(), which is part of the Actor object. 


Figure 4 Check for mouse clicks on 
mouse down, and set all buttons 
back to unlit on mouse up 


Q@1. def on_mouse down(pos): 


02. global myButtons 

Q3. for b in myButtons: 

Q4. if b.collidepoint(pos): b.state = True 
05. 

Q@6. def on_mouse up(pos): 

Q7. global myButtons 

Q8. for b in myButtons: b.state = False 


figures. py 


Q@1. def playAnimation(): 


Q2. global playPosition, playingAnimation 

Q@3. playPosition = @ 7 ae 
d . ‘ igure 5 addButton 

04. playingAnimation = True generates a random 


OS. 


Q@6. def addButton(): 


number between 
0 and 3, then adds 
this number to 


07. global buttonList eieahpurices ren 

08. buttonList.append(randint(@, 3)) rel alah Haas 

Q9. playAnimation() playAnimation() 
function 
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on_mouse_ down 


—=> 


redunlit.png redlit.png 


Above When the mouse is clicked on a button, we switch 
the unlit image for the lit image 


>STEP 08 

Ups and downs 

We can write a test in on_mouse_down() for each 
button, to see if it has been pressed, and then change 
the state of the button if it has been pressed. We can 
then write code to set all the button states to False in 
the on_mouse_up() function, and our update() and 
draw() functions will now reflect what we need to 
see on the screen from those actions. Look at Figure 4 
and you will see how we can change the state of the 
buttons as a response to mouse events. When you 
have added this to your program, test it to make sure 
that the buttons light up correctly when clicked. 


>STEP 09 

Write a list 

Now that we have our buttons working, we will need 
to make a way to use them in two different ways. The 
first will be for the game to display a sequence for the 
player to follow, and the second is to receive input 
from the player when they repeat the sequence. For 
the first task we will need to build a list to represent 
the sequence and then play that sequence to the 
player. Let’s define our list at the top of the code 
with buttonList = [] and then make a function 
def addButton(): which will create an additional 
entry into the sequence each round. 


>STEP 10 

That's a bit random 

We can generate our sequence by generating random 
integers using the random module. We can use this 
module by importing it at the top of our code with: 
from random import randint. We will only need 
the randint() function, so we can import that 
function specifically. To add anew number to the 
sequence in the addButton() function, we can write 
buttonList.append(randint(@, 3)), which 

will add a number between 0 and 3 to our list. Once 
we have added our new number, we will want to 
show the player the sequence, so add a line in the 
addButton() function: playAnimation(). 


>STEP 11 

Playing the animation 

We have set up our function to create the sequence. 
Now we need a system to play that sequence so that 
the player can see it. We will do this with a counter 

variable called playPosition. We define this at the 


raspberrypi.org/magpi 


VIDEO GAME LOGIC WITH SIMPLE BRIAN 


start of our code: playPosition = 9. We will also 
need a variable to show that our animation is playing: 
playingAnimation = False, also written at the start 
of the code. We can then define our playAnimation() 
function that we used in the previous step. Look 

at Figure 5 to see how the addButton() and 
playAnimation() functions are written. 


>STEP 12 

Are we playing? 

So, once we have set our animation going, we will 
need to react to that in our update() function. We 
know that all we need to do is change the state of 
the buttons and the draw() function will handle 
the visuals for us. In our update() function, we 
have to say: “If the animation is playing then 
increment our animation counter, check that we 
haven’t reached the end of the animation and if 
not then light the button (change its state to True) 
which is indicated by our sequence list.” This is a 
bit of a mouthful, so in Figure 6 we can see how this 
translates into code. 


>STEP 13 

Getting a bit loopy 

We can see from Figure 6 that we are incrementing 
the play position each time update() is called. What 
we want to do is keep each button in the sequence lit 
for several refreshes, so we divide the playPosition 
by a predefined number (LOOPDELAY) to get our list 
position that we want to display. We round the result 
downwards with the math. floor() function. To use 
this function, you will have to import the math module 
at the top of your code. So if LOOPDELAY is 80 then we 
will move from one list position (listpos) to the next 
every 80 times update()) is called. 


>STEP 14 

A dramatic pause 

Still in Figure 6, we check to see if we have reached 
the end of the buttonList with listpos. If we have 
then we stop the animation. Otherwise, if we are still 
running the animation, we work out which button 
should be lit from our buttonList. We could just 

say “light that button and set the rest to unlit”, but 
before we do that we have a line that basically says: 
“Tf we are in the second half of our button lighting 
loop, set all the buttons to unlit.” This means that we 
will get a pause in between each button being lit when 
no buttons are lit. We can then just loop through our 
buttons and set their state according to the value 

of 1itButton. 


>STEP 15 

Testing the animation 

Now, ignoring the fact that we have a play button 
ready and waiting to do something, we can test our 
animation by calling the addButton() function. 
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Tutorial 


True 


Q@1. def update(): # Pygame Zero update function 

Q@2. global myButtons, playingAnimation, playPosition 

O35. if playingAnimation: 

04. playPosition += 1 

Q5. listpos = math.floor(playPosition/LOOPDELAY ) 

Q6. if listpos == len(buttonList): 

Q7. playingAnimation = False 

Q8. clearButtons() 

Q9. else: 

10. litButton = buttonList[listpos | 

11. if playPosition%ZLOOPDELAY > LOOPDELAY/2: 
litButton = -1 

12. bcount = @ 

13. for b in myButtons: 

girl if litButton == bcount: b.state = 

ibsys else: b.state = False 

16. bcount += 1 


Figure 6 The update() function with a check to see if the 
animation is playing. If it is, we need to work out which 
buttons to light and move the animation on 


This function adds a random button number to the 
list and sets the animation in motion. To test it, we 
can call it a few times at the bottom of our code, just 
above the pgzrun.go(). If we call the addButton() 
function three times then three numbers will be 
added to the buttonList list and the animation will 
start. If this all works, we are ready to add the code to 
capture the player’s response. 


We can collect the players 
clicks on the buttons just 


by adding another list 


>STEP 16 

| need input 

We can collect the player’s clicks on the buttons 

just by adding another list, playerInput, to the 
definitions at the top of the code and adding a few 
lines into our on_mouse_down() function. Add 

a counter variable bcount = ® at the top of the 
function and then add one to bcount at the end of the 
loop. Then, after if b.collidepoint(pos): we add 
playerInput.append(bcount). We can then test 
the player input to see if it matches the buttonList 
list we are looking for. We will write this as a separate 
function called checkPlayerInput() and call it at 
the end of our on_mouse_down() function. As we now 
have the basis of our game, refer to the full listing to 
see how the rest of the code comes together as we go 
through the final steps. 


MODULO 
OR % 


The % symbol 
is used to get 
the remainder 


after a division 
calculation. 
It's useful 

for creating 
smaller 
repeats within 
a larger loop. 
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CHANGING [Mabaaaelad br tan.py 


THE DELAY Game over man 
The checkPlayerInput() function will check the 


We have used buttons that the player has clicked against the list 001. import pgzrun 
pirat held in buttonList which we have been building up G02. from random import randint 
for timing with the addButton() function. So we need to loop Q03. import math 
our loops, if through the playerInput list with a counter variable @04. WIDTH = 800 
ata — let’s call it ui, and write if playerInput[ui] Q@05. HEIGHT = 600 
slow, decrease != buttonList[ui]: gameOver(). If we get to the 006. 
this value at end of the list and both playerInput and buttonList Q@7. myButtons = [] 
ie top of are the same length then we know that the player has 008. myButtons.append(Actor('redunlit', 
completed the sequence and we can signal that the bottomright=(400,272))) 
score needs to be incremented. The score variable can 209. myButtons[@].state = False 
be defined at the top of the code as score = @. In our Q10. myButtons.append(Actor('greenunlit', 
on_mouse_up() function, we can then respond to the bottomleft=(400,270))) 
score signal by incrementing the score and setting the Q@11. myButtons[1].state = False 
next round in motion. Q@12. myButtons.append(Actor('blueunlit', 
topright=(400, 270) )) 
>STEP 18 913. myButtons[2].state = False 
Just press play 014. myButtons.append(Actor('yellowunlit', 
We still haven’t done anything with that play topleft=(400, 270) )) 
button Actor that we set up at the beginning. Q15. myButtons[3].state = False 
Let’s put some code behind that to get the game Q@16. buttonsLit = ['redlit', ‘greenlit', 
started. Make sure you have removed any testing "pluelit', ‘yellowlit' ] 
calls at the bottom of your code to addButton() Q@17. buttonsUnlit = ['redunlit', 
(Step 15). We will need a variable to check if the ‘sreenunlit', ‘blueunlit', 
game is Started, so put gameStarted = False ‘yellowunlit' | 


Q18. playButton = Actor('play', 


Let's put some code behind aura: 
Q@20. playPosition = @ 


that to get the Qalne Started Q@21. playingAnimation = False 


Q@22. gameCountdown = -1 


at the top of the code with the other variables Q@23. LOOPDELAY = 82 

and then in our on_mouse_up() function we can Q@24. score = Q 

add atest: if playButton.collidepoint(pos) Q@25. playerInput = [] 

and gameStarted == False: and then set the Q@26. signalScore = False 

gameStarted variable to True. We can set a countdown Q@27. gameStarted = False 

variable when the play button is clicked so that there is Q28. 

a Slight pause before the first animation starts. Q@29. def draw(): # Pygame Zero draw function 

Q30. global playingAnimation, score 

>STEP 19 931. screen. fill((30, 10, 30)) 

Finishing touches Q32. for b in myButtons: b.draw() 

We’re nearly there with our game: we have a way to B25. if gameStarted: 
USING TEXT play a random sequence and build that list round by Q34. screen.draw.text("Score : " + 

round, and we have a way to capture and check user str(score), (310, 540), owidth=0.5, 
If you are input. The last things we need are some instructions ocolor=(255,255,255), color=(255,128,9) 
Der heaeas for the player, which we can do with the Pygame » fontsize=60) 
good idea to Zero screen.draw.text() function. We will want Q@35. else: 
elton tel an initial ‘Press Play to Start’ message, a ‘Watch’ Q36. playButton.draw() 
aayest ee) message for when the animation is playing, a ‘Now Q37. screen.draw.text("Play", (370, 
can take a You’ message to prompt the player to respond, anda 525), Owl dun—0. 5, OcOlor—( 255,255,255), 
ialaaaetate score message to be displayed when the game is over. color=(255,128,0) , fontsize=4@) 
pretania Have a look in the draw() function in the complete Q38. if seore > ©; 
You may get listing to see how these fit in. There are many ways B29" screen.draw.text("Final 
aon we can enhance this game; for example, the original Score : " + str(score), (250, 20), 
leacietater electronic game had sound too, but that will be GWidth—O. 5, OGOl0r—(2554255..255)), 


covered in another part of this series. 
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color=(255,128,0) , fontsize=60) Q@82. def checkPlayerInput(): 
040. else: 083. global playerInput, >PYTHON 
041. screen.draw.text("Press gameStarted, score, 
Play to Start", (220, 20), owidth=0.5, buttonList, gameCountdown, DOWNLOAD: 
ocolor=(255,255,255), color=(255,128,0) , signalScore magpi.cc/hPlqsl 
Ffontsize=60) 084. ul = 0 
Q42. if playingAnimation or gameCountdown > @: Q85. while ui < len(playerInput): 
Q43. screen.draw.text("Watch", (330, Q86. if playerInput[ui] != buttonList[ui]: 
205 OWidEn—U. 5, ocolor—(255, 255,255) gameOver() 
color=(255,128,0) , fontsize=6@) Q87. ui += 1 
Q44. if not playingAnimation and gameCountdown == 688. if ui == len(buttonList): signalScore = True 
QO: 089. 
Q45. screen.draw.text("Now You", (310, @98@. def on_mouse down(pos): 
20), OWwildtn=-C.5 .0COlOh—\ 255. 255.255), Q91. global myButtons, playingAnimation, 
color=(255,128,0) , fontsize=60) gameCountdown, playerInput 
046. Q92. if not playingAnimation and gameCountdown == 
047. def update(): # Pygame Zero update function Q: 
048. global myButtons, playingAnimation, Q93. bcount = @ 
playPosition, gameCountdown 994. for b in myButtons: 
Q49. if playingAnimation: Q95. if b.collidepoint(pos): 
Q50. playPosition += 1 Q96. playerInput.append(bcount) 
Q51. listpos = math.floor(playPosition/ Q97. b.state = True 
LOOPDELAY ) 098. bcount += 1 
Q52. if listpos == len(buttonList): Q@99. checkPlayerInput() 
B52). playingAnimation = False 100. 
Q54. clearButtons() 101. def on_mouse up(pos): 
Q55. else: 1962. global myButtons, gameStarted, gameCountdown, 
Q56. litButton = buttonList[listpos | SignalScore, score 
Q57. if playPosition%ZLOOPDELAY > 103. if not playingAnimation and gameCountdown == 
LOOPDELAY/2: litButton = -1 QO: 
058. bcount = @ 104. for b in myButtons: b.state = False 
Q@59. for b in myButtons: 105. if playButton.collidepoint(pos) and 
060. if litButton == bcount: b.state = gameStarted == False: 
True 106. gameStarted = True 
061. else: b.state = False 107. score = @ 
062. bcount += 1 108. gameCountdown = LOOPDELAY 
063. bcount = @ 109. if signalScore: 
064. for b in myButtons: 110. score += 1 
Q65. if b.state == True: b.image = ae gameCountdown = LOOPDELAY 
buttonsLit[ bcount | ilbae clearButtons() 
Q66. else: b.image = buttonsUnlit[bcount ] 113% SignalScore = False 
Q67. bcount += 1 jlilate 
068. if gameCountdown > @: 115. def clearButtons(): 
Q69. gameCountdown -=1 las global myButtons 
070. if gameCountdown == @: ie ee for b in myButtons: b.state = False 
Q71. addButton( ) 118. 
O72: playerInput.clear() 119. def playAnimation(): 
O73. 120. global playPosition, playingAnimation 
Q74. def gameOver(): a playPosition = @ 
O75. global gameStarted, gameCountdown, 122. playingAnimation = True 
playerInput, buttonList 123% 
Q76. gameStarted = False 124. def addButton(): 
Q77. gameCountdown = -1 ilpaye global buttonList 
Q78. playerInput.clear() 126. buttonList.append(randint(@, 3)) 
Q@79. buttonList.clear() 27 playAnimation() 
080. clearButtons() 128. 
Q81. 129. pgzrun.go() 
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WESLEY ARCHER 


Raspberry Pi fan and man behind 
Raspberry Coulis. Enjoys building 
Pi-related projects and writing 
up guides. 

raspberrycoulis.com 
twitter.com/RaspberryCoulis 


MINI PI-POWERED 


Build your own mini smart mirror to display the temperature and humidity 


Youll 
Need 


> Raspberry Pi 
Zero W 


> Micro Dot pHAT 
magpi.cc/ 
2cfq70Ob 


> BME280 sensor 


> Prototyping 
wire and 
soldering iron 


> MOSSEBO 
13x18 cm photo 
frame —- IKEA 


> Reflective mirror 
window film 


> Beebotte 
account - 
beebotte.com 


The data from the BME280 
sensor is displayed on the 
Micro Dot pHAT 


The MOSSEBO frame 
from IKEA is ideal and 
inexpensive for this build 


ew parents can be obsessed with ensuring 

their child is not too hot or cold. Sure, they 

could use a standard thermometer, but that’s 
not as fun as using a Raspberry Pi. Smart mirrors are 
all the rage, and we’ll show you how to build a mini 
Smart mirror to display the temperature and humidity 
ina room. And without breaking the bank. 


Prototype your circuit first 

We recommend testing your circuit with a breadboard 
before soldering them. The BME280 sensor is 3 V 
tolerant, and connects to the SDA and SCL pins on the 
Pi, but shares them with the Micro Dot pHAT, so will 
require intricate wiring and soldering — we found that 
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stripping a small part of the wire in the middle and 
soldering to that so the wire is shared worked well. 
Or you could solder two wires to the one GPIO pin; 1.e. 
one at the top, one at the bottom. 


Applying the mirrored window film 

We found a UK supplier of mirrored window film that 
issued free A5-sized samples — they’ve since started 
charging 99p, which is still great value. Applying the 
mirrored window film is fairly straightforward, but 
make sure you follow instructions! We used soapy 
water, a Squeegee, and patience when applying ours to 
make sure no air bubbles were trapped, and we applied 
two layers to add to the effect. Make sure it dries! 
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To Micro Dot pHAT 


Above The BME280 is connected to 3V, GND, SDA, and SCL pins 
on the Pi. The Micro Dot pHAT is connected to 5V, GND, SDA, and 
SCL as well 


>STEP-03 

Prepare the picture frame 

We chose the MOSSEBO picture frame as it was fairly 
deep and housed the Pi and Micro Dot pHAT perfectly. 
Inside the frame is a white internal frame, which we 
used to hold our Micro Dot pHAT in place by roughly 
cutting a slot into the corner. Don’t worry if this is not 
picture perfect, as it will be hidden anyway. We also 
cut a small gap for the cables to pass through. 


>STEP-04 

Download our code to your Pi 

Now your BME280 sensor and Micro Dot pHAT are 
all connected, and your frame is built, you’ 1] need 

to install the software. Install the Micro Dot pHAT 
libraries (magpi.cc/NtPIsE) as well as sign up for a 
Beebotte XS account (beebotte.com) and then you’ 11 
need to install our code. With Beebotte you can keep 
track of the data sent from your Pi and graph it out. 


>STEP-05 

Install the Beebotte module 

Beebotte works via an API, which is very well suited 
to life on a Pi, but you’1] need to install the Beebotte 
module with sudo pip install beebotte. The 
euide at magpi.cc/AiWqCZ is a great starting point. 
Once installed, you’ll need to create a channel so you 
can store the data sent from your Pi. This generates 
a unique channel token that you’1l need to add to our 
code for it to work, as well as the channel name used. 


>STEP-06 

Test it all out! 

Once you’ve added the Beebotte channel token and 
name, you should be able to test it all out. Type python 
bme280-mdot-beebotte. py at the command prompt 
and you should see the Micro Dot pHAT spring into life 
and cycle through the temperature and humidity. If 

you have created a dashboard to display your data, you 
should start seeing it appear in your account straight 
away. Pressing CTRL+C will exit the code when running. 
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bme280-mdot-beebotte py 


Ol, 
Q2. 
Q3. 
04. 
Oo. 
06. 
07. 
08. 
Q9. 


D2 


>PYTHON 
#!/usr/bin/env python 


DOWNLOAD: 
magpi.cc/FXuLSi 


import bme28@ 


import time 
import sys 
import threading 
from microdotphat import write_string, set_decimal, clear, show 
from beebotte import * 


### Replace CHANNEL TOKEN with that of your Beebotte channel and 
### YOUR CHANNEL NAME with the name you give your Beebotte channel 
bbt = BBT(token = 'CHANNEL_TOKEN') 

chanName = "YOUR_CHANNEL_NAME" 


# These resources needed to be added to your Beebotte channel - 
i.e. 

# Temperature and Humidity. 

temp resource = Resource(bbt, chanName, ‘temperature’ ) 
humidity resource = Resource(bbt, chanName, ‘humidity’ ) 


# Sends data to your Beebotte channel 
def beebotte(): 
while True: 
temp _resource.write(round(temperature, 1) ) 
humidity resource.write(round(humidity, @) ) 
time. sleep(900) # 15 mins to prevent maxing API limit 


# Display stats on the Micro Dot pHAT 
def microdot(): 
clear() 
write _string( "%.1f" % temperature + "C", kerning=False) 
show() 
time.sleep(5) 
clear() 
write string( "%.@f" % humidity + "% RH", kerning=False) 
show() 
time.sleep(5) 


try: 
# Get the first reading from the BME28@ sensor - ignore 
pressure for now. 
temperature, pressure,humidity = bme280.readBME280A11() 
# Start the Beebotte function as a thread so it works in the 
background 
beebotte thread = threading. Thread(target=beebotte) 
beebotte thread.daemon = True 
beebotte thread.start() 
# Run a loop to collect data and display it on the Micro Dot 
pHAT 
while True: 
temperature, pressure,humidity = bme280.readBME280A11() 
microdot() 


# Attempt to exit cleanly - not quite there, needs work! 
except (KeyboardInterrupt, SystemExit): 

sys.exit() 

pass 
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Tutorial WALKTHROUGH 


YOUR CODE 


hen you’ve created a really useful project 
and you want to share it with other people, a 
crucial step is creating documentation that 
helps people understand what the code does, how it 
works, and how they can use it. 

To share the code you’ve created and help people use 
it, you can create a website that documents your project. 

This guide will teach you how to build a website for 
your project that automatically creates documentation 
for your Python code. 

Imagine you’ve created a software masterpiece 
that will make countless coders’ lives a little 
easier, and you’ve made it available, but nobody is 
using it because they don’t know how to! Creating 
documentation is key when you share your code. 

In this project, you will be documenting some 
example code based on a deck of cards project 
(magpi.cc/CEtozb). It’s not essential for you to have 
worked through this project, but it would be useful, 
because it would help you understand what the code 
you'll document does. 
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Create a website that automatically creates documentation for Python programs 


Download the project code called card.py from 
here: magpi.cc/WdQwNP. Then open the downloaded 
card.py program using Python 3 IDLE. 

Look over the code. You will see that there are two 
classes: Card and Deck. Card represents a single playing 
card, while Deck is a collection of cards stacked in order. 
At the bottom of the program, a deck object is created 
from Deck, and a description is printed to the screen. 

Run the card.py program to see how it works. You 
should see a message describing the deck of cards 
printed to the screen (Figure 1). 


| [db Python 3.6 hel - o 
File elt hell Deby Cpt Wir help 

Python 3.6.4 (v3.6.4:d48eceb, Dec 15 2017, 06:54:40) [HSC v.1900 
64 bit (AMD64)] on win32 

Type "copyright", "credits" or "license ()}" for more information. 
RESTART: ©: \Users\Martin O'Hanlon-LT\ Documents raspbhercypilearn 
ing\documenting-your-code\en\ resources \card.py 

Deck of 32 cards 


ee 


__ bei Coea| 


Figure 1 After running the card.py program, 
you should see this in IDLE 
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Documenting your code 

If you look through the card.py program, you will 
notice that there is no additional information in the 
code that describes how it works or how to use it. 

The program is small, so you could probably review 
the code and work out how the interface works and 
what each function does. But what about programs 
that have a thousand lines of code? Or even a million? 
It would be extremely difficult and time-consuming to 
figure out how such big programs work without some 
additional information. 

Python allows you to add information about 
your program into the code using docstrings 
(magpi.cc/KuSYYW). Docstrings are the basis for 
creating documentation for your code. You add 
docstrings at the start of a module, class, or function 
in the form of a string framed by three double 
quotation marks """ on either side: 


def helloworld(): 
""" prints ‘hello world' to the screen 
print("hello world") 


Docstrings can be a single line (as in the example 
above), or they can span multiple lines: 


def helloworld(): 

This function prints ‘hello world’ to the 
screen. 

It accepts no arguments and returns 
nothing. 


print("hello world") 


Your first task is to add a docstring to the Card class 
to describe the class and what it is for. 


class Card: 

The Card class represents a single playing 
card and is initialised by passing a suit and 
number. 


def init (self, suit, number): 


self. suit = suit 
self. number = number 


Do the same for the Deck class 


Generating documentation 
Now that your code contains some information about 
itself in the form of docstrings, you can use Python’s 
pydoc module (magpi.cc/cLunif) to automatically 
create HTML documentation about your code. 

Open a Terminal window and navigate to the folder 
containing your card.py program: 
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card.py 


Q1. import random 
Q2. 
. Class Card: 


61. 
. print(deck) 


DOCUMENTING YOUR CODE 


def 


def 


>PYTHON 


DOWNLOAD: 
magpi.cc/ WdQwNP 


__init__(self, suit, number): 
self. suit = suit 
self. number = number 


__repr_ (self): 
return self. number + 


of " + self. suit 


@property 


def 


suit(self): 
return self. suit 


@suit.setter 


def 


suit(self, suit): 

if suit in ["hearts", "clubs", "diamonds", "spades" ]: 
self. suit = suit 

else: 
print("That's not a suit!") 


@property 


def 


number (self): 
return self. number 


@number.setter 


def 


def 


def 


def 


def 


def 


number(self, number): 
valid = [str(n) for n in range(2,11)] + ["J", "Q", 
if number in valid: 
self. number = number 
else: 
print("That's not a valid number") 
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- Class Deck: 


__init__(self): 
self. cards = [] 
self.populate() 


populate(self): 

suits = ["hearts", "clubs", "diamonds", "spades" ] 

numbers = [str(n) for n in range(2,11)] + ["J", "Q", "K", "A"] 
self. cards = [ Card(s, n) for s in suits for n in numbers ] 


shuffle(self): 
random. shuffle(self. cards) 


deal(self, no_of_cards): 

dealt _cards = [] 

for i in range(no_of_cards): 
dealt_card = self. _cards.pop(@) 
dealt_cards.append(dealt_card) 

return dealt_cards 


__repr__ (self): 
cards in _deck = len(self. cards) 
return "Deck of " + str(cards_ in deck) + 


cards" 


deck = Deck() 
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Figure 2 
Your online 


documentation will 


look something 
like this 


Figure 3 
The file structure 


of Sphinx once it's 
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all installed 


lag Tare Bee en LL eee ey Pa ee ee ee 


cd name_of_folder 


Enter the command to run the pydoc module to 
create documentation: 


python3 -m pydoc -w ./card.py 


When the command has finished running, you will 
be presented with the message ‘wrote card.html’. 
Note that pydoc uses the name of the Python program 
you input as the name for the HTML file. 

Open the card.html file using your web browser to 
see the documentation that’s been created. You will 
see a page that shows the Card and Deck classes, their 
methods, and properties, including the descriptions 
you added as docstrings (Figure 2). 

You could upload this basic HTML page to a hosting 
service to provide your users with information about 
your software. The next steps will show you how 
to use the Sphinx tool to build a documentation 
website to which you can add additional content 
and information. 


Complete the documentation 

Add the rest of the docstrings to the methods and 
properties of the Card and Deck classes to describe 
what they do. 


pi@raspberry: ~/docs 
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Add a docstring directly under the method’s 
definition def: 


def shuffle(self): 
""" A description of what the shuffle 
method does """ 
random.shuffle(self. cards) 


Only add a docstring to a property’s getter that 
describes what the property is — the setter doesn’t 
need one: 


@property 
def suit(self): 
""" Gets or sets the suit of the Card 


return self. suit 


@suit.setter 
def suit(self, suit): 
# there is no need for a docstring on 
a setter 
if suit in ["hearts", "clubs", 
"diamonds", "spades" ]: 
self. suit = 
else: 
print("That's not a suit!") 


suit 


Adding a docstring to the setter will not cause an 
error, but pydoc will ignore it when generating the 
documentation. When you have added docstrings to 
your code, you can run the pydoc command again to 
generate updated documentation. 


Creating a project website with Sphinx 
Using pydoc and docstrings is a great way to create 
structured documentation about your code, but it has 
limits because you can’t add additional information 
and content. 

On a less basic website, similar to for instance 
the one for GPIO Zero (magpi.cc/2pQmvfl), you 
can add a lot more information in addition to 
documentation, such as recipes, FAQs, images, 
and code snippets. 

You will use Sphinx (sphinx-doc.org) to create such 
a project website. This tool was originally created for 
documenting the Python language. 

To create content for your Sphinx website, you 
will write text files formatted using the simple 
but powerful markup language reStructuredText 
(reST): magpi.cc/yDHiZh. 


Install Sphinx 
Open a Terminal or command prompt window and use 


pip3 to install the Sphinx module: 


pip3 install sphinx 
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The Sphinx quick-start program will make a number 
of files and directories where your documentation will 

building [mo]: te 3 | be created (Figure 3). 

spdeting eevironment? 1 added, © changed, @ removed The key files and directory are: 


loading pickled environment.. 
; saat Ceo 


king for now-outdated files... none 


ickling environment... don i conf.py — a Sphinx configuration file that describes 
: how your documentation should be created 


generating 


aarp tages, P ai... lah index.rst — the main page and index of your 
sd : documentation 


g 
dumping search index in Eng] 
dumping object inventory... dom 
build succeeded. 


_build — the directory where your documentation 
will be created 


Build your website 


Figure 4 Building your website should look a Little like this To view your project website, you will need to build it. 
This converts all the project files into HTML files. Run 
Sphinx includes a quick-start utility that creates the following command to build your website: 
a template Sphinx project. Navigate to your project 
directory and run the Sphinx quick-start utility make html 
by entering: 
This will create an html folder within the 
sphinx-quickstart _build directory that will hold the project website 
files (Figure 4). 

Use the following responses to complete the Open the index.html file in the _build/html 
quick-start questionnaire that will determine directory using a web browser. You will see an empty 
properties and settings Sphinx will use for your project site like in Figure 5 (overleaf). 
website — while there’s a fair number of questions, Next, you’ll add your own content to the project 
you’ ll use the default answer for all but four of them site, including auto-generated documentation for 
by pressing ENTER. your code. 

Root path for the documentation [.] Yes 

Separate source and build directories (y/n) [nl] Yes n 

Name prefix for templates and static dir [_]: Yes : 

Project name: No card 

Author name(s): No your name 

Project version []: No 0.1 

Project release [0.1]: Yes 0.1 

Project language [enl: Yes en 

Source file suffix [:rst]: Yes rst 

Name of your master document (without suffix) [index]: Yes index 

Do you want to use the epub builder (y/n) [nl: Yes n 

autodoc: automatically insert docstrings from modules (y/n) [n1: No y 

doctest: automatically test code snippets in doctest blocks (y/n) [nl: Yes n 

intersphinx: link between Sphinx documentation of different projects (y/n) [nl: Yes n 

todo: write “todo” entries that can be shown or hidden on build (y/n) [nl: Yes n 

coverage: checks for documentation coverage (y/n) [nl: Yes n 

imgmath: include math, rendered as PNG or SVG images (y/n) Inl: Yes n 

mathjax: include math, rendered in the browser by MathJax (y/n) Inl: Yes n 

ifconfig: conditional inclusion of content based on config values (y/n) [nl: Yes n 

viewcode: include links to the source code of documented Python objects (y/n) [nl: Yes n 

githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [nl: Yes n 

Create Makefile? (y/n) ly]: Yes y 

Create Windows command file? (y/n) yl: Yes y 
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Figure 5 

The empty project 
website ready 

to have code 
uploaded to it 


@ fe 


Qnuck search 


Be 


AC Used Martin 620) Hanien-LT,Cecume nts temp dees! Build hires irl tr 


[) Welcome to card’s docu x 


C | O file:///C:/Users/Martin%200'Hanion-LT/Documents/temp/docs/_build/html/index.html 


Quick search 


Go 
° Index 
® Module Index 


® Search Page 


Adding your code documentation 

So it can include the code documentation, Sphinx 
needs to know where to find it. You tell Sphinx this by 
modifying the conf.py file. Open conf.py and find this 
section of code: 


# import os 
# import sys 
# sys.path.insert(@, os.path.abspath('.')) 


Uncomment this code by removing the # characters. 


import os 
import sys 
sys.path.insert(@, os.path.abspath('.')) 


Welcome to card’s documentation! 
* (ode dacs 
Indices and tables 


* Module Index 


* Search Pape 


Figure 6 Documentation now appearing in your index 


< CD files///Cy/Users/Martink200 Manion-LT/Oocuments/temp/cocs/_build/Mimi/coce.ntm! ry OB 


Quick search 


Oo 


Code docs 


s card. Card(nat, number) 
ee Re : , deter te eer age a's : : . 
The Card class represents a single playing card and is initialised by passing a suit and number 
, , Pe 
A card is initialised using 
ace of spades =~ Card(“apades™, 
nusbe r 
Returns or sets the number ("2"-"10" C A”) e Card 


Returns: the card number asas 
eust 


pveturms OF sets the suit (carts, chucs, Giamonas, space 


Returns: the card suit as a string 


Figure 7 Documentation is auto-generated from the info we gave it 
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Welcome to card’s documentation! 


Indices and tables 


This adds the current directory (.) to Sphinx’s 
configuration so it can find your code files. Now, 
create a new file called code.rst. This will be your code 
documentation page. Add a title to the page: 


Code docs 


Add the following code to import the card.py module. 


.- module:: card 

Next, add this code to automatically generate the 
documentation for the Card class: 

.. autoclass:: Card 
smembers: 


In order for your code.rst page to appear on your 
project website, it needs to be added to the index. 
Open index.rst and modify it to add the code page 
under the table of contents .. toctree:: — the code 
should look like this: 


Welcome to card's documentation! 


-. toctree:: 
:maxdepth: 2 
:caption: Contents: 


code 
Now rebuild your project website: 
make html 


Reopen the index.html file in the _build/html 
directory using your browser. Your code page will 
now appear in the index (Figure 6). When you open 
the code page, you will see your auto-generated 
documentation about the Card class (Figure 7). 

Update code.rst to auto-generate the 
documentation for the Deck class by repeating the 
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step where you used autoclass to generate the docs 
for the Card class. The code.rst file should look 
like this: 


Code docs 


.-- module:: card 
.. autoclass:: Card 
smembers: 
.. autoclass:: Deck 
smembers: 


Rebuild your website and check that the code page 
now includes documentation for Card and Deck — it 
should look like Figure 8. 


Creating pages 

In addition to pages that describe your code, you 
can include pages with other content on your 
project website. 

All the pages you want to add need to be formatted 
using the reST markup language. This primer 
(magpi.cc/pBzQUQ) will show you how to use the 
most common reST syntax elements. 

To get started, let’s create an About page that will 
display some details about the project and where to 
find more information. Create a new file called 
about.rst and add a title to the page: 


About this project 


Add some text about the project; for example: 


Deck of cards is a set of classes for creating 


playing cards. 


Perhaps add a hyperlink to the project’s source code: 


You can create this project yourself by 
visiting “this page <https://projects. 
raspberrypi.org/en/projects/deck-of-cards> _. 


[) About this project —car xX 


€ C © file:///C:/Users/Martin%200' Hanion-LT/Documents/temp/docs/_build/html/about.htm! wT 


Quick search 


DOCUMENTING YOUR CODE 


@®) file///C/Users/Manin®200 Hanion-LT/Oocuments/temp/docs/_build/Niml/code.nimi 
er ‘ode docs 
Quick search ( Ode GOC 


ass cord. Card (ncdt, monber) 


Tutorial 


ite Varad class represents & singie Playing Cara aNd 65 ifitalsed OF Passing & Suit ANG NuMoes 


Returns: the card number as a serine 


svusat 


Returns: the card suit asa 
clase card. Deck 


deal' 


Deals (and removes) a number of cards from the deck 
Returns: lut of Card objects 


populate(|) 


*opulates (resets) the deck of cards with all 52 cards in the order 2-10, J 


tus, CiamMords, spacdcs 


shuffile\) 


‘ * ' sy : . . : 
Shuttles the Geck ints « rancom order of “ne card 
=PUlties tive GOck iit 2 TAMGOM Ofaer OF Playing Caras 


Figure 8 You're almost done! 


When you have finished creating your about.rst 
page, add it to the index. rst file. 


Welcome to card's documentation! 


-. toctree:: 
:maxdepth: 2 
:caption: Contents: 


about 
code 


Rebuild your project to see your new page using the 
following command: 


make html 


And you’re done! Check Figure 9 to see how it 
should all look. You can add more pages to your 
project site now, e.g. starting with FAQs. 


vie kt 


About this project 


Deck of cards is set of classes for creating playing cards. 


Go 


You can create this project yourself by visiting this page. 
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Figure 9 Now you 
can add separate 


pages to your 
website 
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Wolfram 


Language 


Wireless 
connection 


MinecraftLink 
Library 


Figure 1 Adding 
the MinecraftLink 
library to 

the Wolfram 
Language extends 
it with these 

new commands 


wv Minecraft 


MinecraftChat 


PROGRAMMING 


MINECRAFT PI 


WITH WOLFRAM LANGUAGE 


Combining Wolfram Language and Minecraft provides 


a fun playground for learning coding 


f you are a gamer, you can use the richness of 
the Wolfram Language to programmatically 
generate all kinds of interesting structures 

in the game world of Minecraft, or to add new 
capabilities to the game. If you are a coder, then you 
can consider Minecraft just as a fun 3D rendering 
engine for the output of your code. 

First, make sure that your Raspberry Pi is up to date 
and then open Mathematica. Install the MinecraftLink 
Library by entering the following code, followed by 
SHIFT+RETURN to evaluate: 


PacletInstall["MinecraftLink" ] 


The MinecraftLink library adds a set of new 
commands to the Wolfram Language for connecting 
to a running Raspberry Pi Minecraft game. You will 
find basic documentation on them by searching 
for ‘Minecraft’ in the Wolfram Help system. Start 
by launching Minecraft on the Raspberry Pi, and 
then start a fresh game or open an existing one. 

In Mathematica, load the library by evaluating: 


MinecraftGetPlayers MinecraftSetCamera 
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MinecraftClearHits 
MinecraftConnect 
MinecraftGetBlock 
MinecraftGetBlockID 
MinecraftGetBlockIDWi 
thData 
MinecraftGetHeight 
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MinecraftGetPosition 
MinecraftGetTile 
MinecraftHitHistory 


MinecraftRestore 


MinecraftSave 
MinecraftSetBlock 


MinecraftSetPosition 
MinecraftSetProperty 
Orientation 


SMinecraftBlockNames 


<< MinecraftLink 


Don't overlook the grave accent (""") at the end. 
You can find the new commands in Figure 1. If you are 
connecting from a different computer, you must tell 
Mathematica the IP address of the Raspberry Pi: 


MinecraftConnect["10.10.163.22" ] 


You don’t need to do this if both programs are 
on the same machine, but if you need to reset the 
connection, you can use MinecraftConnect or 
MinecraftConnect[ "localhost" J. 

Let’s test to see if that worked by evaluating: 


MinecraftChat[ "Hello from the Wolfram Language" | 


You should see the message ‘Hello from the 
Wolfram Language’ appear briefly in the game. 
Minecraft uses a simple {x, y, z} co-ordinate system, 
where x and z are the horizontal directions and y is 
the vertical direction. You can see the co-ordinates 
in the top-left corner of the screen, but to get them 
programmatically you can use: 


MinecraftGetPosition| | 


We can teleport the character to a new location (in 
this case, up in the air): 


MinecraftSetPosition[{@, 50, 0}] 
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MinecraftSetBlock[pos, "Dirt", 
Plot[Sin[x], {x, @, 12}, Axes > False], 
RasterSize > 18] 


>WOLFRAM 
LANGUAGE 


DOWNLOAD: 
magpi.cc/GTpzNv 


If the content is a 3D geometry, then it will be 


of e 


Above After evaluating your code, this message should appear 
briefly in the game chat area 


If we have just started a game, then 10 blocks 
in front of us is {0,10,0}. But depending on how 


mountainous the terrain is, that block might be above 
or below ground. We can find the surface level with: 


y = MinecraftGetHeight[{@, 8}] 
2 


We can test that by looking at the block at that 
position. It should be Air: 


pos = {@, y, 8} 
MinecraftGetBlock|[ pos | 


Now we can Start building. We can place blocks of 
any type — for example, ‘Wood’: 


MinecraftSetBlock[ pos, "Wood" ] 


You can specify the block material by name, BlockID 
number, or using an Entity. We remove them by just 
overwriting the block with something else, such as ‘Air’: 


MinecraftSetBlock[pos, "Air" ] 


One reason to use the Wolfram Language for this 
is that it handles all kinds of interesting 2D and 3D 
objects, and we have set up the SetBlock command to 
handle these fairly automatically. For example, let’s 
paint a letter X in the sky in gold: 


MinecraftSetBlock[pos, "GoldBlock", "X"] 
By default, rasterized content will be 12 blocks wide, 
so if you need more detail, you can increase that with 


an option. 


MinecraftSetBlock[pos, "GoldBlock", whe 


rasterized in 3D: 


MinecraftSetBlock[pos, "Wood", Sphere[], 
RasterSize > 50] 


There are lots of 3D geometry primitives and they 
can be combined in many ways, including cuboids, 
a pyramid, and a sphere to make a basic house. We 
can look at our creation from the air by controlling 
the camera: 


MinecraftSetCamera[ "Fixed" ]; 
MinecraftSetCamera[{®, 25, 6}]; 


We can interact with blocks that you hit using the 
right mouse button while holding a sword. The left 
mouse button just places and smashes blocks, but the 
right mouse button creates events that wait for us to 
read and act on them. You can read these with: 


MinecraftHitHistory[ ] 


This shows that since the game started, we have done 
two of these special hits, each time on the same block 
at {-1,2,2, on face number 1 (the top of the block). We 
are player 1, but there could be multiple players. We 
can fetch these pieces of information by position and 
name. For example, MinecraftHitHistory[-1] is the 
last hit, and we can extract its ‘Position’ information 
and use that co-ordinate in MinecraftGetBlock to 
discover the type of block that was most recently hit. 

This shows that since the game started, we have done 
two of these special hits, each time on the block at 
{-1,2,2}, on Face 1 (the top of the block). We can fetch 
these pieces of information by position and name. 

As well as giving you a simple programming 
interface to Minecraft, similar to other languages, the 
Wolfram Language contains hundreds of high-level 
functions that let you develop much more exciting 
projects quickly. You might want to check out some of 
the 3D geometry, 3D image processing, and built-in 
data sources as a Starting point. 


Figure 2 Anything 


you can create 
in the Wolfram 
Language can be 


made into blocks, 


RasterSize > 50] like this plot of the 
MinecraftSetBlock[pos, "Air", foe ; ae 
RasterSize > 50] 
Use "\[WolframLanguageLogo]" to type: AS 
Anything you make can become blocks. Here is a plot 
of the function sin[x] (see Figure 2): 
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Tutorial 


CODING GAMES 
ON THE RASPBERRY PI 


IN C/C++ ESS: 


Code::Blocks 


sudo apt-get 
codeblocks 


stb_image.h 
installed 
previously 


USE THE 
TEXTURE 
SPACE WELL 


Having lots of 
small textures 


is good for 
visualising, 
but bad for 
drawing group 
images in as 
few textures 
as possible. 


Optimising your game so it doesn’t quite run as slow 


ast time we had a #define that seemed 

to give us a massive speed boost: it totally 
changed the game from being a slow and 
unplayable but clearly-all-there game, to actually 
being a little too fast — all by setting one value. 

Why was there such a massive difference? Well, 
it’s nothing to do with the #define itself — all that 
did was tell our compiler that if the defined value was 
true, to compile a different chunk of code between 
the #if, #else, and #endif directives. 

This is known as a compiler directive; it causes 
different code to be produced and is frequently used 
to selectively test and debug code or add extra output 
features we don’t want to include in a final build. 


Why so slow? 

But why was the code initially so slow? It harks back 
to that concept we already described of a bottleneck. 
Every time we get the CPU to talk to the GPU, we 
need to wait for the GPU to wake up from its intense 

dreams of shifting triangles; hit its snooze button 
(twice); get its dressing gown on; find its slippers; 
stumble down the stairs; check through the spy-hole 
to see who’s there; recognise the CPU delivery man; 
fumble for the door keys; take a couple of bits of info 
at a time, closing the door and stacking the parcels 
of info, then ask the CPU for another couple. When 
done, it goes back to bed to continue to dream. 

It’s only fast when it’s left to its own devices doing 
what it loves to do. And while the GPU is doing its 
eetting-up routine, our CPU is waiting around. 
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There’s nothing really wrong with the code we 
wrote in terms of it doing what we want it to do. Tiles 
are on screen, sprites are on screen, Bob moves as 
he’s supposed to, it’s all there and working! It just 
didn’t take into account the fact that our GPU and 
our CPU really don’t like to talk to each other, and we 
made them talk to each other a lot. 

So game programmers become more than a little 
OCD over how long things take, but also, when and 
where to do things — and whether or not the same 
results apply, which allows us not to repeat the 
same things. By setting the #define FastUpdate 
flag to true, we altered the way our graphics were set 
up and updated. Rather than talk to the GPU each 
object update, we let the CPU focus on the logic and 
the tiles didn’t need to draw themselves until after 
the logic was done. 

We also took note that our tiles aren’t actually 
going anywhere, they’re always visible at the same 
point at the same time, so why should we ever be 
transferring their data from the CPU to the GPU? 
Much better to set up a GPU-side storage buffer 
called a variable buffer object (VBO), to hold all that 
position info and avoid the transfer each frame. The 
GPU is happy to work with data that it already has 
access to, which lets it work at its fastest rate, not 
talking to the CPU - which doesn’t need to wait. 


Optimising is king, but... 


If optimising is so important, then why didn’t 
we optimise from the start? Mainly, we did that 
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CODING GAMES ON THE RASPBERRY PI IN C/C++ 


to really impress on you as anew coder the quite 
devastating impact of badly designed code, but also 
to encourage you that usually it only needs a simple 


change and a think about how we do things to get our 


performance back. 

Over time, as you get better at coding, you will 
amass a small toolkit of dos and don’ts; this is one of 
your first don’ts. 

Optimising also has a bit of a downside: the code 
can become less readable and clear. Our intent to 
draw is very obvious when we See it in our update 
functions, but now we’re delaying the actual draw to 
some time after the updates are all done. So are we 
sure they are ready to go° 

Therefore, what we’ve done is to move most 
of the setting up of the tiles to a one-time VBO 
initialisation, which enables us keep the data in 
one place that the GPU can access instantly. Then, 
rather than do a draw call for each tile object — all 
2560 of them — we draw all our tiles with one draw 
call. The differences are very clear to see. The 
conclusion should be obvious: avoid doing too many 
draw calls! 


Planning for bigger things 

Only the sprites — in this case Bob — really need to 
move on screen, making it impossible to keep an 
unchanged VBO of his position info, and that’s the 
only object that currently still has a CPU-to-GPU 
update in its code update, but... what if we have 
100 sprites? 
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We are lucky here, because we are really only going 
to have a few sprites on screen, so we can probably 
get away with continuing the update/draw cycle. 
However, it’s really much better if we take the hint 
that faster is better. 

That means that rather than draw them every 
object update, we need to find a way to draw them 


Tutorial 


Figure 1 Simple 
individual frames 


Optimising also has abit ofa 
downside: the code can become 


less readable and clear 


just after we draw the tiles. One solution is to keep a 
note of the updated sprites data needed to draw, in 
a CPU buffer, which can be sent direct to the GPU in 
one draw call. 

Doing a draw call from a CPU buffer is much slower 
than doing a draw call from a VBO, but sadly the 
Sprites move, so their positioning is variable, as is 
their current frame for animation. So there’s just no 
benefit to setting up the CPU buffer, making a VBO, 
then calling the draw. We will just allow the CPU to 
send the data directly. 

This is just one of those things we need to learn 
to live with. Variable or dynamic data can’t easily be 
stored in the GPU memory, only in the CPU’s. So we 
just have to try to limit it to the least amount needed, 
Store it until the data is complete, and then send 
when ready. 


KEEP 
CLASSES 
SMALL 


Keep only 
what you 

need to keep 
in a class; try 
to separate 
objects into 
individual 
classes and 
avoid catch-all 


types. 
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*s OK to do 


s not too hard to visualise. 


) 


Review the source code to see how our new faster 


but slightly less readable code is doing its thing. 


We also need some optimising on our textures. One 
Adding the baddies 


texture per frame means we set up the texture before 
each draw call, but if we arrange all our images into 


one texture, we only need one set up. 
It does force us to use a different way to address 


See Figures 1 and 2. We keep the six faces/frames 
of a die in one texture, which allows us to reference 
them using what are known as UV cords (we use 
UV to avoid confusion with XY for position). These 
represent fractions of the size of the texture, from 
0.of to 1.0f along its U and V co-ordinates. Imagine 
you Said halfway along and halfway down is the start 
of the image we want; that means a UV of 0.5f, 0.5f. 
One more limitation: all the sprites need to have 
the same shader, since we set up the shader we need 
before the draw call. If we want to have a couple of 
so within reason, but don’t chop and change. 


different shaders, for different effects, it 


each frame, but that 


If the sprites share so much info, then we can in 
principle define a data pattern that consists of: 


WALKTHROUGH 


Figure 2 So many 
maps, so few tiles 
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. . . . . . . . . . . * . . . . . . . . . . . . 
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We could make a class called ‘Baddies’, but we want 
a number of them to do different things, which would 
mean keeping code for different types of baddies in 


the same class and having flags or type variables to let 


solidity. Though we don’t make them climb, as they 
your update and draw systems know what to work on. 


and obey some basic rules of gravity and platform 
don’t really need to. 


Just like Bob, our baddies interact with the map, 
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> X and Y co-ordinates, and the defunct Z 
If we define a small data structure to contain this 
info, then we have a fairly simple way to create an 


>» Texture co-ordinates 


> Quad vertices 
array, or vector, of the structure and, when the time 


comes, we set it up as the ‘attributes’ we want to 


send to the shaders to draw. 


be baddies 
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WORK FIRST 
slow code. 
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Below Baddies will 
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The baddies work in almost the same way as Bob, on position and frames, and add them to the update 
except of course they don’t use key inputs, they use and draw cycles. Feel free to add your own types 
their own logic. They use our SimpleObject base of baddies! 
class and all we need to do is focus on how they work Now review the code. Notice how the update code 
for their own logic. Nothing too fancy here, we’re really is very small, and quite focused on the specific 


going to define two basic types of baddie which have logic needed for the specific class. 
a few simple logic states they can switch between. So ; 
now we introduce the wait-and-chase baddie, anda Next time 


point-to-point baddie. We’ ve tackled most the key elements, but our 
The wait-and-chase baddie isa mushroom graphic game looks a bit naff: because of our hi-res screens, LEARN 
with a walk sequence and a hide graphic, and has our full-screen display and small sprites are really MORE 


| | ABOUT C 
We want something a bit more chunky and retro, 


and that means we need to consider the view area 
of our screen and how much we make visible 


Brian hasa 
whole book 
on the subject 
of making 
games C and 


C++, called The 


Fundamentals 
only two states: wait and, erm, chase. Waiting is rather small and hard to see. We want something of C/C++ Game 
F rr ; ; Programming: 
not an idle ‘do nothing’ kind of wait, though: the a bit more chunky and retro, and that means Using 
mushroom is testing each frame to see if Bob isclose weneed to consider the view area of our screen Target-based 
to him; if so, he switches to a chase state and if he and how much we make visible. These are the Development 
; ; on SBCs. Grab 
escapes, goes back to a wait state. basics of scrolling. + hore: 
Point-to-point, as you can imagine, is simply a Because our game logic is running detached from magpi.cc/ 
case of our baddie walking to one point, changing any concept of what the screen looks like, we can nUKjEt 
direction, then walking to another. Since many Zoom Our screen to any part of the map we want. And as 
types of baddies may want to use this, it can be an if we choose to zoom to a variable point, for example THE rina, 
inherited class for others who use the logic, but not around where Bob is moving, we can effectively get C/C++ GAME mull OF 
‘ : Using Target-based 0 AMMING 
the draw systems. scrolling which follows Bob as he moves around. seen lopment on SBC's 
Both baddies are simple contact enemies which We need to make quite some changes to the way Se : 
we can signal to the main loop, or to Bob’s code, our shaders work and how we view the play area to 
that he’s been hit. For now we will just recognise get this to work well, so that’s our job next time. 
it, and act on it soon. With that done, all we need Again, we ran out of space to do text, so once we 
to do is make absolutely sure we set them up in the eet scrolling up and running, we’ll dedicate the rest wo 
game initialisation, give them some starting info of the space to doing text. ies Ras te 
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YOUR QUESTIONS ANSWERED 


FREQUENTLY 
ASKED QUESTIONS 


NEED A 
PROBLEM 
SOLVED? 


Email magpi@raspberrypi.org or 
find us on raspberrypi.org/forums 
to feature in a future issue. 


Your technical hardware and software problems solved... 
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ELECTRONICS 
ar RE EMBEDDED SYOENS? 


EMBEDDED 


Embedded 

An embedded system is a (usually small) computer 
system that performs a dedicated function within 

a large system. They basically control or monitor a 
smaller part of a larger system, and are generally only 
used for one specialised thing. 


Benefits 

Computers are designed to perform multiple 
functions, either at once or separately. Why this 
erants them great flexibility for day-to-day use, it 
means they’re not always optimised to perform a 
single task. Dedicated embedded systems/chips can 
not only work better for a specific task; they’re usually 
cheaper in bulk as well. 


Raspberry Pi 

Due to the tiny size of the Raspberry Pi, it’s great 

for prototyping systems that can then be made 
embedded. Because it’s also pretty cheap, some 
people tend to just stick with the Raspberry Pi as the 
embedded device in their system — there’s even a 
specialised version of the Pi that aids in this, called 
the Compute Module. 


Full-size Pi 

Raspberry Pi models like the 2, 3, 3B+, and even 
the Model As to a lesser extent, are widely available 
so are great for prototyping. Although they’re still 
small, they’re not the smallest Pi boards, and the 
more powerful Pi models require more electricity 
as well. Depending on the project, this could be a 
serious weakness. 
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Pi Zero 

The Zero is an excellent choice for embedded systems 
as it’s tiny and requires very little power to run in 
comparison to its bigger siblings. It also runs a little 
faster than the Model A+ by default. The main issue 
you might find with it is buying in bulk, though, 

and it’s nowhere near as powerful as something 

like a3B+. 


Compute Module 

The Compute Module is a special version of the 
Raspberry Pi specifically made for industrial 
applications. It’s tiny and includes a standard DDR2 
SODIMM connector to plug into projects, flash 
memory, and more. The full dev kit is a bit more 
expensive than a normal Pi, but it’s a lot better suited 
for these kind of tasks. 


No kits 

Unfortunately, you can’t get a kit to make a Pi. 
Raspberry Pi boards come with all the components 
pre-soldered, so you can’t get a basic kit and then pick 
and choose what components to add. This has been 
the case since the Pi was first released in early 2012. 


Desoldering 

This doesn’t mean you can’t desolder components 
from your Raspberry Pi, though — although we’|I say 
that this is not recommended and can be dangerous 
unless you know exactly what you’re doing (and 

don’t mind voiding your warranty as well). We’ve 

seen people make incredibly slim Raspberry Pis by 
removing some of the more bulky connectors from the 
top part of the board. 


Customisation service 

The Raspberry Pi can be customised by element14, 
however, depending on the customer’s needs. This 
way, you get the kind of Pi you need without having to 
do any of the hard work yourself. You can find more 
info about this (and whether or not it’s for you) here: 
mMagpi.cc/eyipPm. 
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CAN | EXTEND THE PI CAMERA MODULE RIBBON CABLE? 
Yes. We have reports of people using cables up to 

4m in length and still receiving acceptable images, 
although your experience may differ. 


CAN I HAVE A CAMERA WITH MORE MEGAPIXELS? 

No; the Raspberry Pi Camera Modules are the only 
cameras that are compatible with the Raspberry Pi's 
Camera port. There are currently no plans to release a 
higher-resolution sensor. 


HOW MUCH POWER DOES THE CAMERA MODULE USE? 
The Raspberry Pi Camera Modules requires 250 mA to 
operate. Ensure that your power supply can provide 
enough power for the connected Camera Module, as 
well as for the Raspberry Pi itself and any peripherals 
directly attached to it. 


Having trouble with your subscription to The MagPI? 
Here are your most common questions answered: 


How can | find out details about my print subscription? 


For all print subscription enquiries, please contact 


rpipresshelp@raspberrypi.org — this includes changes of 


address, and finding out when your subscription ends. 


| seem to be missing an issue of my subscription, 
what should I do? 


DOES THE RASPBERRY PI COME WITH A CASE? 

An official case for the Raspberry Pi is available from 
our distributors. There are also lots of home-brew case 
discussions on the forum, as well as several third-party 
cases available. We suggest stopping by the cases 
sub-forum and reading some of the threads about 
cases you can purchase or build yourself. 


DOES IT FIT IN AN ALTOIDS TIN? 

It is possible to make a case for the Raspberry Pi 

out of an Altoids tin: there are instructions givenina 
forum post at magpi.cc/gLTrYB (the directions are 
also available as an Instructables guide). However, 
you may find that this is not possible with older 
boards, as their form factors are not as neat. You can, 
of course, fit a Pi Zero into an Altoids tin with plenty of 
room to spare. 
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Unfortunately, things do get lost in the post. If that’s the 
case, make sure to email rpipresshelp@raspberrypi.org. 
Include your name, the email address you signed up with, 
and which issue you're missing - all being well, they will 
send you a replacement issue. 


If | re-subscribe for a year, do I get the free Pi Zero W 
bundle again? 

Yes. We think the world of re-subscribers and we treat 
them just as well as new subscribers. You'll get whatever 
free gift we include for people taking out a year's 


subscription (currently a Pi Zero W starter kit), whether it’s 


your first sub to The MagPi or your fourth. 
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feature | MAKING MUSIC 


K.G. ORPHANIDES 


K.G. is a writer, developer and lapsed 
session musician. They're currently 
working on environmental audio for the 
Codename Caerus game project. 
twitter.com/kgorphanides 


TURN YOUR 
RASPBERRY PI INTO 
A 


WITH DIGITAL 
AUDLO WORKSTATLON 
SOFTWARE 


Speakers/ 
headphones for 
audio monitoring 
- use the best 
ones you have 


MIDI keyboard 


(optional) ompact, silent, and started with audio production and Qtractor DAW (digital 
USB audio bs capable of seamlessly and show you how to set up your audio workstation). We’ll also 
interface integrating with Pi for low-latency digital audio introduce tools for playing MIDI 
oenene professional- quality USB audio recording and MIDI synthesis. instruments using your computer 
MiDlinstrument devices, your Raspberry Pi In the process, you’ll keyboard, editing notation with 
auplcey, can become a complete home use software including the your mouse, and exporting 
LLbvwo recording studio. We’llintroduce JACK Audio Connection Kit, your recordings into easily 

the free tools you’ll need to get FluidSynth software synthesizer, distributable formats. 


Qtractor is a stable tracker-style 
digital audio workstation for MIDI 
on a a i ga NR ASSCES and digital audio recording 


Po ee ee ee = 
2 0 " +* ) 


Qs 

h ynth front 

woe to output MID; Taare 
ndard audio device gha 


66 | MaddPi August 2018 


The Raspberry Pi has limited 
memory and processor power and 
lacks an integrated line input, but 
with some external hardware and 
judicious software choices, the 
latest Raspberry Pi 3 B+ is 

easily up to the task of 

producing and editing complex 
multitrack music. 


digitally. Bit depthisa 
measurement of how much data is 
used to encode the digital signal. 
CD-quality audio has a sample 
rate of 44.1kHz and a 16-bit bit 
depth. When recording digital 
audio, you should treat this as your 
minimum quality requirement. 
Higher sample rates and bit depths 


CD-quality audio has a 
sample rate of 44.1 kHz 
and a 16-bit bit depth 


HOW DOES 

DIGLTAL AUDLO 
RECORDING WORK? 
When you record sound digitally, 
an analogue-to-digital converter 
(ADC) in your recording device cuts 
the analogue waveform into 
sections that will be encoded as 
data using a technique called 
pulse-code modulation (PCM), 
with its accuracy determined by its 
sample rate and bit depth. 

Sample rate, also called sample 
frequency, refers to the number of 
Slices that an analogue waveform is 
divided into while it’s recorded 
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are supported by many audio 
devices, and are useful in specific 
recording situations, but we’re 
going to stick with our software’s 
default settings, with a sample rate 
of either 44.1 kHz or 48 kHz, 
depending on your hardware. 


WHAT IS MIDI? 

MIDI (Musical Instrument Digital 
Interface) is a standardised method 
of transmitting and encoding 
musical signals, first devised in the 
early 1980s. It records input from 
MIDI instruments as a Series of 
instructions that encode the pitch, 


MAKING MUSIC 


duration, velocity — the dynamics 
of the note, such as the force with 
which a key is struck — and other 
audio characteristics of each note, 
including effects such as pitch 
bends, tuning, and decay. 

While older MIDI hardware used 
five-pin DIN connectors, most 
modern devices send MIDI over 
USB. For this tutorial we’ll use a 
software synthesizer, or soft synth, 
to read MIDI input and play it 
through a digital-to-analogue 
converter (DAC) such as those built 
into USB audio interfaces or the 
Pi’s Broadcom BCM2835 SoC, 
using software instrument banks 
called SoundFonts. 


The first step 

in configuring 
your audio 
environment is 
to tell JACK to 
use ALSA and 
your interface - 
a Propellerhead 
Balance USB 
device in 

this example 
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If you just have a Raspberry Pi, 
with no USB audio or MIDI input 
devices of any kind, you can still 
start making music. For MIDI 
composition, you can enter notes 
using a mouse Or use virtual 
keyboard software to play in real 
time using your PC keyboard as 
an instrument. 

For digital audio, libraries of 
royalty-free samples are available 
online to edit together into tracks 
of your own. You can also import 


You can also import recordings 
made on other devices 


recordings made on other devices, 
such as your smartphone. The only 
hardware you definitely can’t do 
without is a pair of speakers or 
some decent headphones. 


GEAR UP 


To record a range of live 
instruments, though, you’ll want a 
USB audio interface with multiple 
inputs to handle analogue-to- 
digital conversion. Popular entry- 
level options include the Behringer 
U-Phoria UMC404HD and the 

IK Multimedia iRig Pro Duo. Our 
screenshots show the - sadly 
discontinued — Propellerhead 
Balance audio interface. 

If you want something even 
cheaper and simpler, look for a 
1/,-inch TRS (guitar) lead to USB 
converter, which includes a tiny 
sound card to digitise your audio 
output, such as the Behringer 
Line 2 USB. 

For vocals or acoustic instrument 
recordings, a USB condenser mic 
— which acts as its own dedicated 
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USB audio input device - isa 
good place to start. The Samson 
Meteor Mic is a solid budget choice, 
while Blue Microphones’ Yeti Pro 
is fantastic and can double as a 
standard XLR mic if you have more 
to spend. 


THE SOFTWARE 
MACHINE 

Digital audio workstation (DAW) 
software gives you a fully featured 


environment to record, edit, and 


Lingot guitar tuner; MuseScore 
notation editor and VMPK (the 
Virtual MIDI Piano Keyboard) 
to control a MIDI synth using 
your computer keyboard; and 
the Audacity audio editor, which 
provides a cleaner environment to 
edit digital audio waveforms. 

To install all the software you’ll 
need for this tutorial, run the 
following in a Terminal window: 


To record mono 
instruments 
like guitars in 
Qtractor, you 
should create 

a dedicated 
mono bus 


sudo apt install 
qjackctl qsynth qtractor 
fluid-soundfont-gs vmpk 
musescore lingot audacity 


We’ll also need a MIDI instrument 
definition file to go with our 
SoundFonts, so download the 
open-source Standard.ins file 
from magpi.cc/Llbvwo. 


JACK lets you 
run virtual 
wires between 
devices like 
your MIDI 
keyboard, DAW, 
and soft synth 


combine both audio tracks and 
input from MIDI devices. They’ 11 
typically include modules that 
can record MIDI data live as you 
play it in via a keyboard, notation 
or piano roll editing tools, digital 
audio recording and editing tools, 
and mixing capabilities to help you ak 
balance audio from various sources. ee OIG rs 

In this tutorial, we’ll use Qtractor. Otracto = = = ‘oupcas 
Although it isn’t as fully featured - RGATSTFLUID synth 
as some of its rivals, with the 
conspicuous absence of a notation 
editor and MIDI step entry, it’s 
particularly simple to use and is 
extremely stable on the Pi. 

To ensure optimal recording 
quality and avoid lag, particularly 
when playing along to previously 
recorded digital audio tracks, 
we’ll be using the JACK Audio 
Connection Kit (JACK for short) 
low-latency audio daemon 
to handle audio routing and 
connection, and FluidSynth to give 
voices to our MIDI keyboard. —_ 

We'll also install a handful of - « 
other useful musicians’ tools: the fate 
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MIDI input is 
shown as a 
sequence of 
discrete tones 


Linux has integrated support 

for class-compliant USB audio 
hardware. Plug in your audio 
interface and MIDI keyboard, 
boot your Pi, and you’re ready 

to go. We’Ill start by loading our 
software and setting up the JACK 
audio daemon to correctly route 
our MIDI devices. 

QjackCtl - the GUI control 
interface for the JACK low-latency 
audio driver — is installed by 
default on Raspbian, but isn’t 
visible in the menus. To make it 
appear, go to Preferences > Main 
Menu Editor in the Raspbian 
menu, select Sound & Video, and 
place a tick next to QjackCtl before 
clicking OK. 


Digital audi 
: 10 recordj 
isplayed as a waveform wi 


Alternatively, you can start it 
by running QjackCtl in a Terminal 
window, which we’re going to do, to 
simultaneously launch it alongside 
the other software we’ll need: 
Qsynth to run a software synthesizer 
that outputs MIDI via our audio 
device, and the Qtractor DAW. 


qjackctl & qsynth & qtractor 


The QjackCtl window may spawn 
with its title bar off screen. If this 
happens, hold ALT on the keyboard 
and use the mouse to drag it intoa 
more convenient location. 

Click the Setup button in 
QjackCtl, make sure the ALSA driver 
is selected, and choose your audio 


Five magnifying 9 
you to zoom Inan 


output device from the Interface 
pull-down. If you’re using the Pi’s 
built-in sound, you want hw:ALSA 
bcm2835. If you’re using a USB 
output device, select that instead. 
Click OK and then press Start on the 
JACK control panel. 

Go to Qsynth and select Setup. 
Click on the SoundFonts tab and 
click Open. It should automatically 
open the /usr/share/sounds/sf2 
directory, where you’ll find the 
General MIDI (GM) and Roland 
General Standard (GS) SoundFonts 
we installed earlier. Select both of 
them and click Open. 

Having returned to the setup 
menu, highlight the FluidR3_GS.. 
SoundFont and click the up, 


Li 
oe See ee ee! FS 
1 ion ; “| Ls 


lass icons allow 
d out on tracks 


August 2018 MdgPi | 69 


feature | MAKING MUSIC 


Tools Transport Help 


ee ST 
ee a ee 


pi MIDLdem 9-Track1 7 | thome/pi/Otractor! 
button to make it the default 
SoundFont, then click OK. Allow 
Qsynth to restart. 

Go to Qtractor and, from the 
View menu, select Instruments. 


Click Import and browse to where 
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you saved the Standard.ins file 

we downloaded earlier. Select it 
and click Open, then select Close 
and save the instrument changes. 
You’ll now be able to select GM and 
GS MIDI instruments by name. 


Make sure your USB MIDI keyboard 
is connected - or, if you don’t have 
one, open VMPK (Virtual MIDI 
Piano Keyboard) from the 
Sound & Video menu. 
Go to QjackCtl and 
press the Connect button. 
This is where you string 
together virtual wires 
connecting your different 
devices to one another. 


Make sure the ALSA tab is selected. 
You should see a list of input and 
output devices. In our example, we 
want to connect our MIDI keyboard 
to Qtractor for input and Qtractor 
to FluidSynth for output. 

To do this, click and drag from 
the keyboard in the Readable 
Clients / Output Ports list on the 
right, to Qtractor in the Writable 
Clients / Input Ports on the left. 
Then drag from Qtractor on the 
right to FluidSynth on the left. 

Before you can use Qtractor to 
play or record MIDI input, you’ll 
have to create a MIDI track. Right- 
click in its main workspace and 
select Add Track, select MIDI as its 
type, Roland GS as its instrument, 
Roland GS Capital Tones as its 
Bank, and any voice you fancy in 
Program. Then click OK. 

You can change a MIDI track’s 
instrument at any time by right- 
clicking on it and choosing a voice 
from the Instrument submenu. 


The first time you create or 

start recording a track, you’ll be 
prompted to name your session 
and select a save directory. It’s 
advisable to create a folder called 
Qtractor in your home directory for 
this. Once you’ve started working 


on a piece of music, remember to 
save often by pressing CTRLtS. 

To record MIDI input in real 
time, select the track you want to 
record to and arm it by pressing 
the R button just below its name. 
Make sure the Play-head transport 
— indicated by a red line - is at the 
beginning of the track by using the 
BACKSPACE key, the Backward 
toolbar button, or dragging it 
into place with the mouse. Then 
press the red Record button in the 
toolbar and, finally, press Play to 
begin recording. 

Press Stop or hit SPACE when 
you’ve finished. When you finish 
recording on that track, remember 
to press the R button again to 
un-arm it. 

If you need a click track to play 
along to, press the Metronome 
icon on the toolbar or select 
Metronome from the Transport 
menu. You can change the tempo 
and time signature of your piece in 
the Current tempo and Snap/Beat 
sections of the toolbar. 

Once you’ve recorded a MIDI 
passage, you can remove blank 
Space or unwanted bars from the 
beginning and end by dragging 
the blue Edit-head and Edit- 
tail markers to the beginning 
and end of the section you 


wish to remove and pressing 
CTRL+SHIFT+DELETE. The Loop 
function lets you use similar 
markers to define a section you 
want to listen to repeatedly. 

If you need to manually tidy up 
your recording, double-click on 
the track to open the piano roll. 
Here, you can See individual notes 


you'll want a notation editor. 
Qtractor doesn’t have one built in, 
but we installed MuseScore earlier. 
Qtractor saves and exports 
its MIDI sections as .mid files, 
which MuseScore can open and 
edit. MuseScore gives you fine 
control over the pitch and length 
of notes, and can also play back 


To record MIDI input 1n real 
time, select the track you 
want to record to and arm 1t 


and their characteristics, such as 
pitch, timing, and velocity. You 
can select, move, and delete notes, 
or apply effects to entire sections 
of music, such as quantization to 
make their timing line up precisely 
with the beat. You can also draw in 
new notes using your mouse. 


If you’re more comfortable 
working with a traditional musical 
score than a piano roll, or if you 
want to print and share your 
composition for live performance, 


SO te A & Oo io0% 
pa Oe SP Oe) 


| Palettes ” 


“ Page View 


1 aa | 


3 Untitled & sons* x 
* Grace Motes 


* Clefs 

* Key Signatures 

> Time Signatures 

+ Barlines 

> Lines 

m * Articulations & Ornan 
* Accidentals 
* Dynamics 
> Repeats & Jumps 
, * Tempo 


iy 
Electric Guitar 6 } 


Electing Bass od } 
) > Text 


> wreaks & spacers Violoncelios FFF 
+ Beam Properties 


4 
Electric: Guitar 6 } 
7 


Diromect EJ j 


MIDI files through JACK: go to 
Edit > Preferences, choose the I/O 
tab, and select JACK audio server 
before saving these settings and 
restarting the program. 


Qtractor can also handle digital 
audio recording from microphones 
or the instrument inputs of a 

USB audio interface. For most 
instruments, such as electric 
basses, violins, and guitars, you’ll 
want to configure a mono input for 


[% Te concert Pitch oO] 
b bb és 


% 


Text charset: | UTF-2 


* 
Sore Muse Score ingbrument 


hand quant! 
! 


Téth] 

Electric Guitar vail 
Gtr! 
vocill 

16tt 

‘ a hal 


Overdrive Gkr 
Fingered Garg Electric Bass 


Cre: r 
Strings 7 Violoncellog 


feature 


inspector 


Nothing selected 


14 -e 


August 2018 MdagPi | 71 


feature | MAKING MUSIC 


your file before you record. Open 
the View menu and select Buses. 
We’re going to make a copy of the 
Audio Master bus. 

To do this, select it and then, 
in the Properties box, type ina 
new name to replace Master -— 
Mono would be best. In the Mode 
pull-down, replace Duplex with 
Input and under Audio, reduce the 
number of Channels to 1. Then 
click the Create button. 

Save your file once you’ve 
done this, as bus configuration 


a Were golng to make 
a copy of the Audio 
Master bus 


is per-project. Adding a bus can 
sometimes interfere with JACK, 
so it’s a good idea to set your bus 
up before you start work on your 
project. If you stop being able to 
hear MIDI or audio, you may have 
to shut down and restart Qtractor, 
Qsynth, and QjackCtl. 
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With your bus configured, 
return to the main interface and 
press SHIFT+INSERT or use the 
right-click menu to create a track. 
Set its type as audio, its Input as 
Mono, and its Output as Master. 
You should be able to hear your 
instrument through your monitors. 

Recording audio tracks works 
much like recording live MIDI 
input: press R on the track to arm 
it, move the Play-head transport to 
wherever you’d like to start, press 
the red Record button, press Play, 
and start strumming. 


Because Qtractor uses FluidSynth 
to handle its MIDI voices, you can’t 
directly export MIDI tracks as PCM 
audio suitable for compression and 
distribution as an MP3. 

However, once you’re happy with 
the MIDI elements of your track, 
you can record them as PCM audio 
by creating a new audio track using 
the Master bus for both input and 
output. Press F8 to open Qtractor’s 
JACK Audio connection interface; 
expand the Qsynth outputs on 


the right, the Qtractor inputs on 
the left; and drag Qsynth left to 
Qtractor Master/in_1 and Qsynth 
right to Qtractor Master/in_2. 

Return to OQtractor’s main 
interface, arm the audio track 
by pressing R, rewind to the 
beginning of your piece, press the 
red Record button in the toolbar, 
and then press Play. 

While it’s a little circuitous, this 
method creates a perfect PCM audio 
rendition of one or more MIDI 
tracks, which you can then easily 
mix, apply effects to, publish, or 
export for further editing. 


The default view for audio 
waveforms in Qtractor is rather 
cramped but, hidden in the 

lower right corner of the main 
workspace, you'll find a set of 

five magnifying glass icons. You 
can use these to zoom in on your 
waveform so you can cut and paste 
parts of the track, which you select 


by enclosing the section you want 
between the edit heads. 

Qtractor’s design is heavily 
informed by tracker-style 
sequencer software, which 
makes it well suited to building 
up a track from short loops and 
samples. However, if you have a 
particularly long recording that 
you want to clean up, the Audacity 
audio editor, which we installed 
earlier, provides a quick and easy 
range of dedicated tools for fast 
waveform editing. 

To export digital audio tracks 
from Qtractor, select the track, go 
to Track > Export tracks > Audio 
and save it as a WAV file, which 
can be opened in Audacity. 

Audacity uses ALSA audio by 
default, so don’t forget to switch 
it to JACK in the Preferences 
settings or via the right-hand 
pull-down menu just above the 
main workspace. 

Using Audacity, it’s easy to 
cut away the parts you don’t 
want: just select a section of your 
track by dragging the mouse 
and press CTRL+X to cut it, 
CTRL+tC to copy 
it, or DELETE 
to remove it 
entirely. Cut or 
copied audio 
will be pasted 
in wherever you 


click or over any section of audio 
you select. 

A powerful effects menu can 
radically or subtly alter your 
recording. When you’re happy, you 
can use the File > Export menu to 
Save your edited composition as a 
WAV to reimport into Qtractor for 
further mixing. 
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higher quality, lossless codecs like 
FLAC, which retains all your sound 
data but results in larger file sizes. 
Whichever you choose, don’t 
forget to add appropriate track 
name and credit metadata. 
You can publish and stream your 
music for free on bandcamp.com 
and soundcloud.com, while 


A powertul effects menu can radically 


or subtly alter your recording 


When you’ve finished working 
on a composition in Qtractor, you 
can use its Export Tracks feature to 
mix down every selected track in 
your workspace into a single WAV 
file, which you can again open in 
Audacity to export into a smaller, 
more listener-friendly format. 


MUSIC PUBLISHING 


It’s important to hang on to 

a lossless, multitrack copy of 

your recordings, but for online 

distribution it’s usual to compress 

files using either a 
lossy codec such as 
MP3 - which throws 

out parts of audio 

data likely to be 
inaudible to the 
human ear — or, for 


independent distribution services 
such as cdbaby.com are able to 
publish your music on platforms 
including Spotify and iTunes for a 
small fee. 


Audacity also 
allows you 
generous save 
preferences, so 
audio details 
can come up 
on playback 
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Raspberry Pp) Pof-HAT 
(4) Raspberry Pi 2017 


RASPBERRY PI 


POE HAT 


Power your Raspberry Pi directly from a PoE-capable Ethernet socket 


ower over Ethernet (PoE) 
has been a much requested 


R elated Raspberry Pi feature 
from the community. The ability 
PI POE to access power and network 


SWITCH HAT along a single cable could prove 
tremendously useful in a range 


Features 

an Ethernet of deployments. 

socket on the Until now, third-party solutions 

as, have been available, most of which 

cable. The PoE add a second Ethernet socket via 

Switch HAT is the HAT and then pass power on to 

pea ian the USB power port. 

eee eae However, the Raspberry Pi 

However, it is 3B+ added four extra GPIO pins 

also compatible “ ¢: 
specifically to support PoE options 

with older P y PE P 

Raspberry Pi and subsequently announced 

Model B-style this PoE HAT, a Class 2 device 


SHAS for drawing power directly 


from a network. 

This is a more elegant solution 
that draws its power directly 
from the Ethernet connection 
on the Raspberry Pi 3B+ and 
transfers the power via the four 
new GPIO pins on the board, while 


(£30 / $40 
magpi.cc/yAcjMp 
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simultaneously enabling a direct 
network connection. 

The PoE HAT board uses a 
custom-built isolation transformer 
(this is the small white circuit) to 
turn the 37-57 V DC from Ethernet 
to a Raspberry Pi-acceptable 5V. 

The isolation transformer 
doesn’t need much space, and the 
designers have decided to double 
up with another oft-requested 
feature: a fan. 


All of this makes the PoE 
HAT an appealing addition to 
the Raspberry Pi, especially for 
industrial users. Being able to draw 
power from a network makes the 
Raspberry Pi easily deployable 
away from electrical sockets. And 
the presence of a fan provides 
a layer of security when using 
a Raspberry Pi long-term ina 
hot environment. 
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« (¢) Raspberry Pi 201% 


Because the 3B+ is the only 
Raspberry Pi to feature these 
additional PoE pins, you must 
use this HAT with a Raspberry 
Pi 3B+ (no other model is 
currently supported). 


Setting up 

Connecting the Raspberry Pi PoE 
HAT to the Raspberry Pi 3B+ isa 
simple 30-second job. The HAT 
connects directly to the 40-pin 
GPIO header (and four-pin PoE 
header) on the 3B+ board. 

Four standoffs and eight screws 
are used to keep it in place. Then 
it’s simply a case of connecting a 
PoE-enabled Ethernet cable to the 
Raspberry Pi board. It then boots 
up without the requirement of the 
USB power cable. A slot for the Pi 
Camera Module enables you to feed 
its cable through. 

It is possible to add a riser to the 
HAT to extend the GPIO pins out, 
in case you wanted to add a second 
HAT or access the GPIO on the 
Raspberry Pi. The HAT uses I?C to 
interact with the Raspberry Pi. 

At this point, we must stress 
the requirement that you have 
a powered Ethernet connection. 
Most household routers provided 
by the likes of Virgin and BT do not 
supply power over the Ethernet 
connection. Neither do many 
power-line adapters. Check that 
you have your PoE system in place 
before setting up the PoE HAT. 
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For this test, we used a 
TP Link Gigabit PoE Injector 
(magpi.cc/LKGEMO) connected to 
a Virgin Media HUB 3.0 broadband 
router (magpi.cc/kKDKBac) 
The engineering team used a 


NETGEAR GS108PEv3 8-Port Gigabit 


PoE Smart Managed Plus Switch for 
testing (magpi.cc/LlaBWo). 


RASPBERRY PI POE HAT 


£18 / $20 


In terms of networking, the 
Ethernet connection remains a 
Gigabit connection running via the 
USB 2.0 sockets and thus limited 

to 200Mbps. We found no network 
difference using the PoE HAT. 

A more interesting test is 
the fan, which in our testing 
knocked roughly 10°C off the 
CPU temperature. 

The Raspberry Pi without a fan 
idled at 40.8°C; with the fan it 
idled at 32.2°C. Without a fan and 
playing high-definition YouTube 
video, it ran at 60.1°C; with a fan it 
dropped to 42.9°C. 

We even ran a Raspberry Pi with 
all four cores stressed to 100% for 
half an hour and the temperature 
peaked at 53.7°C (we don’t 
recommend doing this on your own 
Raspberry Pi incidentally, so we’re 
not disclosing the test — email us if 
you want to know how). 


An appealing addition to the 
Raspberry Pi, especially for 
industrial users 


Once assembled, the Raspberry 
Pi 3B+ and PoE HAT would not fit 
inside the Raspberry Pi official 
case. It may well be that a case 
option is available down the line, 
but the product brief says ‘This 
product should be operated in 
a well-ventilated environment 
and, if used inside a case, the case 
should not be covered.’ 


Testing the fan 
The PoE HAT conforms to 
the 802.3af PoE standard 
(magpi.cc/cDxYYm) and on the 
board is an isolated switched- 
mode power supply. It’s a37-57V 
DC, Class 2 device that provides 
the 5V/2.5A DC output used bya 
Raspberry Pi. 

In terms of testing, we powered 
it up and used it without a USB 
connection plugged in. 


Neither the HAT, the powered 
Ethernet cable, nor the isolated 
switched-mode power supply 
generate any additional heat, so 
the fan isn’t a required component 
for PoE Ethernet support, but it 
will be a good addition for users in 
high-temperature environments. 

This is ideal for folks who use the 
Pi intensely and worry about the 
long-term effects of stressing the 
CPU without any form of cooling. 


fast word 


A fantastic solution to a long-requested feature. 
The PoE HAT enables the Raspberry Pi to 
draw power directly from a powered Ethernet 


connection. The bonus inclusion of a fan enables 
you to run a Raspberry Pi for long periods in hot 
environments with confidence. 
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We are 
putting a 
new lease 
of life into 


vintage B&O 


speakers 
HiFiBerry 


BEOCREATE 


4-CHANNEL AMPLIFIER 


PI-DIGIAMP+ 


This HAT 
provides no- 
frills good audio 
quality. A DAC 
and 2*35W 
amplifier ona 
single board. 
Perfect for more 
entry-level 
projects. 


magpi.cc/MWwKNe 


Upcycle vintage speakers into the digital age with this 


audiophile- grade HAT amplifier from Bang & Olufsen 


omewhere, in the darkest 
recesses of your garage 
or loft, there may be 
speakers. Not speakers like today’s 
tiny, tinny Bluetooth excuses, but 
proper speakers: large, heavy, 
loud. Although these monoliths 
are Still capable of outperforming 
today’s examples, they are 
becoming increasingly useless. 
Why? Well, unless you’ re holding 
on to your vintage amplifiers, 
there’s nothing left to drive them. 
So your wonderful, expensive 
pieces of engineering excellence sit 
gathering dust, playing only John 
Cage’s 4'33". Until now. 
Audiophile giant Bang & Olufsen 
has partnered with HiFiBerry to 
produce the Beocreate, a high- 
end digital sound processor and 
amplifier for the Raspberry Pi. Not 
so much a HAT as a full fedora, 
scarf, and cape, this monster 


76. | MadgPi August 2018 


upgrades your favourite tiny 
computer to audiophile quality. 
Four channels (a whopping 2x60 W 
and 2x30 W) can be configured to 
drive not only standalone speakers, 
but also their individual woofers 
and tweeters. The on-board DSP 


some software, and you’ve got a 
Bluetooth, Spotify, and AirPlay 
speaker like no other. B&O has 
targeted its classic CX50 and CX100 
speakers, providing built-in profiles 
for the DSP to get the absolute best 
from them and guides to install 


The sound quality 1s enough 
to get the credit card twitching 


can be endlessly configured over 
the web, even in real-time as 
you’re listening, allowing for an 
incredible amount of tinkering 
that will have even the most 
dedicated perfectionist thinking 
‘Oh, that’1l do’. 

The Beocreate also upcycles 
your Classic speakers to work with 
21st century music sources. Add 
a Pi, hook up the wires, install 


everything inside the speakers. The 
good news is it also works with any 
passive speaker, providing a default 
‘safe’ profile that you can then 
tweak if you see fit. 


Get what you pay for 

For a rather breathtaking £149, 
you do get very good build quality. 
On board are a power input (which 
also powers your Pi), four speaker 


raspberrypi.org/magpi 


terminals, and 
TOSLink connectors for 

digital input and output, 
enabling multiple Beocreates 
to be chained together. Your 

Raspberry Pi plugs in upside- 
down, with thoughtfully provided 

posts to hold it firmly in place. You 
can then power both boards from a 
single power supply (not supplied). 

All that remains is to wire in your 
speakers and load up some software, 
a choice between a read-to-go 
image for ‘it just works’ or a more 
customisable Raspbian build with 
drivers and configuration already 
in place. Setup is a breeze despite 
confusing documentation. You can 
set up your WiFi connection and add 
sources such as AirPlay and Spotify 
Connect within a few minutes. 

Once your double-decker-bus- 
scale speakers are down from the 
loft, you may struggle to work out 
where to connect them. There is 
a distinct lack of labelling and we 
restored to trial-and-error. Once 
connected, the result was pretty 
astonishing. Some of us of a, ahem, 
‘middle-aged’ persuasion have 
forgotten the golden age of speakers 
as convenience has compromised 
audio quality. The depth and range 
of sound was wonderful. The point 
of this became obvious. 
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BEOCREATE 4-CHANNEL AMPLIFIER 


Digging deeper into the 
capabilities of this device, it 
supports the creation of DSP 
‘profiles’ using the provided 
SigmaStudio software. You can 
play endlessly with crossover 
frequencies and filters, create a 
setup you like, and then store it on 
the Beocreate so anything playing 
on the Pi uses it. This is a level of 
control that can only have been 
imagined just a few years ago. 


Audio excellence 

This is an unapologetically 
audiophile product — and in this 
case, that means expensive yet 
still value for money. If you just 
want to convert an old average 
speaker, there are cheaper options 
available. The documentation 

is described as in ‘beta’ and we 
couldn’t agree more. Although 
installation was easy, it was not 
obvious where to start, causing 
some initial frustration. That said, 
the sound quality is enough to get 


~ the credit card twitching. 
If you’ve got a snazzy pair of 
speakers stashed away that never 
seem to make it down to the skip 
and you want to give them a new 
lease of life, then the Beocreate 
may reintroduce you to a world of 
incredible sound quality that many 
thought had been lost in portable 
speakers, earbuds, and laptops. 


The last 
time these babies 
made sound, there 
were still three 
living Beatles 


An audiophile'’s dream, the Beocreate is the 
missing link between the worlds of classic high- 
end speakers and modern streaming technology. 
As documentation improves, this will be solid 
choice for bringing your digital music back to life. 
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The 
Simplest way 
to properly 
power your 
Pj Zero with 
g battery 


JuiceBox Zero 
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JUICEBOX ZERO 


Portable power for your Pi Zero. Phil King recharges his battery 


illed as the only battery 
management board in this 
form factor that requires no 
code, JuiceBox Zero can be used as 
a plug-and-play device to provide 
portable power to your Raspberry 
Pi Zero. Well, it’s not quite plug- 
and-play, since you first need to 
solder on a stacking GPIO header 
(not supplied) and also provide your 
own battery. 


PIJUICE It’s compatible with any 3.7V 
If you need more al Tee 
sophisticated or 4.2V single-cell Li-ion or LiPo 
power battery with a two-pole JST PH 2mm 
management connector, 1A current output, and 
options, PiJuice h vod ; 
offers plenty 1A charge rate. Note: while we're 
and it comes informed that multi-cell batteries 
supplied with a may work, they should only be used 
swap-outable 
nasG AL if you know for sure they have a 
reliable cell-levelling mechanism — 


if in any doubt, don’t risk it! 


> e Put it together 

~ $ To mount the JuiceBox Zero on 
your Pi Zero’s GPIO pins, you’ ll 
need to add your own stacking 

header: the online instructions 


magpi.cc/vOlyQP 


78. | MdgPi August 2018 


(magpi.cc/LJMmLh) advise 
mounting this on the Pi Zero first, 
adding a couple of stand-offs (not 
supplied) to secure the JuiceBox Zero 
on top, then soldering the header 
pins. Using a stacking header will 
enable you to add a pHAT/HAT on 
top. There shouldn’t be any pin 
conflict issues since the JuiceBox 
Zero only uses power, ground, and 
GP1016 (can be changed to GPIO25). 

That GPIO pin is used to trigger an 
optional automatic shutdown (after 
you add a single-line cron job) if the 
battery voltage falls below 3.2V, at 
which point a low-battery red LED 
is also lit. 

As well as providing power to the 
Pi, the JuiceBox Zero doubles as a 
battery charger. Just plug a standard 
2A or greater supply into its micro 
USB port; there are helpful LEDs 
to indicate when the battery is 
charging and fully charged. A nice 
bonus is the inclusion of a handy 
on/off slider switch and mounting 
holes for a Pi Camera Module. 


Unlike the rival PiJuice, there 
are no extensive software- 
based power management 
options on offer, but the 
JuiceBox Zero does its job 
well, providing portable power 


and doubling as a battery 
charger. When plugged into 
the mains, it can also be used 
as an uninterruptible power 
supply (UPS). 
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CoderDojo 


Canlstarta 
CoderDojo club 
in my local area? 


CoderDojo is a global network of free, volunteer-led, project-based 
programming clubs for children aged 7-17. Dojos are championed by 
individuals all around the world who are passionate about giving young 

people the opportunity to learn to code. 


Incredibly 
rewarding experience 


“| started a Dojo to give my kids a place to meet other children also 
interested in programming and making games. | get to see them 
making new friends, learning from one other, and they loved it. 
Realising how | had created such a wonderful place for children has 
ignited a spark in me.’ 

- Maroes, CoderDojo NL 


Start your own club. Join us at CoderDojo.com 


The CoderDojo Foundation is Irish Registered Charity (524255) CHY20812 . 
and Is part of the Raspberry Pi Foundation, UK registered charity 1129409 eae eS Raspberry PI 
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RASPBERRY PI 
BESTSELLERS 


Serverless, cloud, containers - whatever 
you need to admin, O'Reilly probably has 
q concise intro guide for it. 


CLOUD NATIVE 


INFRASTRUCTURE — | 


Authors: Justin Garrison 
& Kris Nova 

Publisher: O'Reilly 

Price: £31.99 

ISBN: 978-1491984307 

magpi.cc/LkIKxn 


Infrastructure impacts business; 
get the overview of cloud native 
infrastructure, and how it can 
support a scalable business. From 
patterns to predictions, a high- 
level but technical view of design 
and best practice in the cloud. 


PRACTICAL 
MONITORING 


Author: Mike Julian 
Publisher: O'Reilly 
Price: £21.50 


ISBN: 978-1491957356 
magpi.cc/_LHbBFd 


Anear perfectly balanced overview 
of designing and implementing 
monitoring from your app down 

to infrastructure. Julian's neutral 
approach gives you practical 
knowledge that will work with your 
chosen tools, or get you to ask the 
right questions on tool choice. 


DEPLOYING 
TO OPENSHIFT 


Author: Graham Dumpleton 
Publisher: O'Reilly 

Price: £31.99 

ISBN: 978-1491957165 
magpi.cc/ YuLldP 


Containers, Security-Enhanced 
Linux, and Kubernetes are all 
brought together in OpenShift. 
This quick reference guide to 
Red Hat's container deployment 
and management platform will 
show you the magic that makes 
OpenShift so popular. 


MagPi August 2018 


GET PROGRAMMING 
WITH HASKELL 


Author: Will Kurt 
Publisher: Manning 
Price: £24.32 

ISBN: 978-1617293764 
magpi.cc/KULNCC 


You know you 
want to learn 
Haskell, admit 
it. Maybe you’ve just done a bit 

of Python, but are intrigued by 
what you hear about functional 
programming. Maybe you code 

in a dozen other languages, but 
never got past the elitist talk of 
Applicative Functors and Monoids, 
and keep putting off a look at the 
language whose advanced features 
have been creeping into every 
other programming language for 
the last couple of decades. Perhaps 
the upfront load of theory learning 
in Haskell books prevents you 
really grokking it. 


GOOD HABITS 
FOR GREAT 
CODING 


Author: Michael Stueben 
Publisher: Apress 

Price: £19.99 

ISBN: 978-1484234587 
magpi.cc/tFQWhq 


Learning good 
programming style 
is not easy, but the quickest — and 
possibly only — way is to take 

on coding challenges, reflect on 
experience, and remember the 
lessons learned. So maintains 
Michael Stueben, who brings four 
decades of coding and teaching 
experience to this excellent but 
idiosyncratic guide. 

During a quick intro detailing 
what makes Python great (Python 
is used throughout this book, but 
it aims to teach good style to new 
coders using similar languages), 
Stueben also introduces refactoring 
and optimisation before the reader 


Worry no more, Kurt has written 
this book especially for you. You 
learn by doing, and absorb theory 

and abstract concepts only once 

you have practical examples to 
build the learning upon. This 
is what Get Programming with 
Haskell gives you. 

Some choices may be 
questioned, such as using Haskell 
Platform (Stack is introduced 
later), but it’s a sensible 
pragmatic choice for a book also 
aimed at non-UNIX users. Short 
lessons filled with exercises and 
interactive code snippets to run 
in the REPL keep you moving 
forward, and are organised 
into units which each finish 
with a project. An outstanding 
introduction to Haskell and 
functional programming for real- 
world use. 


Score 


has even noticed starting, and dives 
into an interview code question. 
An allegorical diversion brings in 
unit testing, code reviews, and 
documentation, before delving 
into pain management for new 
programmers. There are many 
good practices that eventually 
experience can teach you — but 
you’ll save a lot of pain by starting 
them early! 

The writer holds strong 
opinions — e.g. scepticism of OOP 
— but an opinionated guide is just 
what’s needed until the learner can 
justifiably argue from experience 
against their mentor’s style. A 
number of rather simple errors 
that should have been caught in 
editing occasionally bring the 
reader up short, but overall this 
is a useful and enjoyable book 
which will considerably boost 
any beginner-to-intermediate 
Pythonista’s skills. 


Score 
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NEURAL NETWORKS 
FOR ELECTRONICS 
HOBBYISTS 


Author: Richard McKeon 
Publisher: Apress 

Price: £14.99 

ISBN: 978-1484235065 
magpi.cc/ezQzZJ 


With the take-off 
of deep learning, there 
is no shortage of resources to 
teach you about neural networks 
— often modelled with Python. 
It’s a strange concept to learn, as 
we’re starting with an answer, 
then looking to train a network 
with cycles of back propagation 
until that answer can be reached: 
mimicking the way the brain 
works. Something that can perhaps 
be more clearly shown by a direct 
analogue, rather than matrix 
multiplication in code. 

McKeon takes that analogue 
approach, and shows how 
to construct a modest but 


FLASK WEB 
DEVELOPMENT 


OREILLY 


Author: Miguel Grinberg 
Publisher: O'Reilly 
Price: £35.99 

ISBN: 978-1491991732 
magpi.cc/ WIUELF 


Flask is the web 
framework that 
doesn’t get in your way. Its 
simple, extensible design makes 
a great foundation for any web- 
based project, but also makes it 
hard to get a grip on just what the 
programmer should do to get the 
best from it. You should certainly 
start with Flask before Django 

if you’re considering your first 
Python web project, as you’ ll be 
coding closer to the action and 
learning more as you go. 

Grinberg does a great jobina 
few short chapters of giving you 
the basic nuts and bolts of Flask, 
from templates — separating 
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functioning neural network from 
simple electronic components 
ona breadboard. Although 
primarily aimed at makers and 
electronic hobbyists who want 
to understand neural networks, 
there’s enough info provided 
for electronics newcomers to be 
able to build the circuit. 
The project that the network 
is being trained on is to build 
an XOR logic gate. This is 
accomplished with careful training, 
well illustrating the neural network 
concept. Voltmeters and adjusting 
potentiometers make the process 
so much more hands-on than 
software, and this would be a great 
school project. Additional functions 
are tried at the end of the book, 
and the possibilities of a simple 
three-layer network leave the 
reader hungry for more learning in 
deep learning. 


Score 


business and presentation logic 
— through database connections, 
to the culmination of part I 
in the organisation of 
large projects (which in 
turn is an example of the 
book’s concern with good 
software engineering). 

The real learning happens 
as you work through the 
example in part II, a social 

blogging application. Having 

one thoroughly worked- 
through project enables the 
reader to see how it all fits 
together as she works through 
authentication, roles, social 
relationships and database 
joins, content posting, etc. The 
final section covering testing, 
performance analysis, and 
deployment is full of practical 
advice. This is essential reading 
in your Python journey. 


Score 


ESSENTIAL READING: 
UPSKILLING ESSENTIALS 


Use the quiet days of summer to improve 
an area of your programming skills - 
from ML to concurrency 


Web Scraping with Python 


Author: Ryan Mitchell 
Publisher: O'Reilly roy 
Price: £31.99 4 Dy, 
ISBN: 978-1491985571 bi “4p! 
magpi.cc/alhfCh with s'ython 


Until every source of internet data 
has a well-crafted API, web scraping 
will be an essential need — and this an 
essential guide. 


Level Design 


Author: Christopher W Totten 
Publisher: CRC 
Price: £40.99 ao 


S44 MS 
ISBN: 978-1498745055 os a 
Fascinating collection of essays from itisonace w, ror : , 


games developers and academics that 
could bring gamification in your loT app 
to the next level! 


Practical Concurrent Haskell 


Authors: Stefania Loredana Nita 
& Marius Mihailescu 

Publisher: Apress 

Price: £35.99 

ISBN: 978-1484227800 

magpi.cc/ pKBULX 


Dive into Haskell and concurrency, and 
you'll be equipped for big data from 
your Pi cluster on up to the cloud. 


Modeling and Simulation 
of Everyday Things 


Author: Michael W Roth 
Publisher: CRC 

Price: £53.99 

ISBN: 978-1439869376 
magpi.cc/JLkklW 


Bringing together maths, C++, and 
visualisation in an occasionally playful 
introduction to usefully modelling the 
real world on your computer. 


Machine Learning 
with Python Cookbook 


Author: Chris Albon 
Publisher: O'Reilly 
Price: £47.99 

ISBN: 978-1491989388 
magpi.cc/OjtfYy 


Machine ¥ \ 
Leaming 
with Pythor 


LCookb 00k 


Take your Pandas and Scikit-learn 
knowledge to real ML challenges with 
a cookbook that combines tutorial with 
reference qualities. 
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BERRY } PI 
PROJECT BOOK 


VOLUME 3 — 


£12.99 


200 pages of 


RASPBERRY PI 


PROJECTS BOOK 


Ce MOLUMES 


Amazing hacking and making projects 
from the makers of MagPi magazine 
Inside: 
® How to get started coding on Raspberry Pi 
® The most inspirational community projects 
® Essential tutorials, guides, and ideas 


@® Expert reviews and buying advice 


Of le ® 
Ce magpi.cc/store 


plus all good newsagents and: 


WHSmith BARNES&NOBLE 


f Available on the | GET IT ON 


App Store > Google Play 
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A picture tour of the amazing Raspberry Fields event! 


he first Raspberry Fields event occurred at the 

end of June, and we were there in the thick of it 

during the hot Cambridge weekend. Hundreds 
of people attended to see some amazing talks, shows, 
and demonstrations. If you missed the event, here area 
load of excellent photos that should help make you feel 
like you were actually there... 


Demos of amazing Pi 
projects were fun for 
all ages and types 
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aay 


Look, up in the sky! 
Is it a bird? A plane? 
No, it’s the air-con 
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Cubert 2.0 was 
a huge draw 
for the crowds 


MO EW. =| 2 
Re 7 SAW 


A FESTIVAL OF DIGITAL MAKING 


,, Lots of Raspberry Pi Our very own Features 
(ox folk helped out over Ed Rob Zwetsloot with 
; the weekend his new friend 
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Parents and 
teachers got to 
talk to Foundation 
representatives 


Performances during 
the weekend ranged from 
interactive light shows to 
explosion-laden science! 


Everyone loved 
the Pi robots 
being shown off 
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CROWDFUND 


[ Here are some other great 
Raspberry Pi projects you can ig hs h 
m crowdfund this month things we saw this mont 


tat 
By 


FA r, j 
f\, ‘h 
4 bl j f 


A custom Raspberry Pi- 
powered guitar, creating 

most excellent digital music 
through tapping (pressing the 
strings to create a note, as 
opposed to holding a chord and 
strumming). The design is great 
as well, with the Raspberry Pi 
visible through clear acrylic on 
the rear of the guitar. 


OFF-GRID MOBILE 
MESH NETWORK 


These portable network routers allow you to create 
a mesh network while outdoors, or even within your 
own home. They run on Raspberry Pi boards and can 
also be very useful for using Raspberry Pi devices, 
especially when outdoors. 


Awe 


Game Boy and retro console hacks are very popular, 
usually gutting a machine and completely replacing 
the electronics. This build is different, though - using a 
custom PCB, Reddit user abhg2 has managed to hack 
a humble GBA SP to be able to connect a Raspberry Pi 
Zero while still using much of the same old hardware. 


This custom Rubik's cube may 


U C AN A U Ni IVE RS AL not quite look like the original 


puzzle, but it works just Like it, 


VEHICLE BUS DECODER albeit using a controller rather 


than your hands to physically 


Want to see your in-car telemetry° The idea of this spin it. We wonder how much 
crowdfunding campaign is to finance decoding of this will throw Rubik's cube 
the necessary data to a UCAN ecosystem. It runs on pros? Would their muscle- 

a Raspberry Pi, so you’ll be able to display data that memory betray them? Either 
your (modern) car has but doesn’t usually show. way, it looks pretty cool. 
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WITH RASPBERRY PI 


The Raspberry Pi takes another dip into medical computing 


The working 
prototype has 
been shown off 
at many Maker 
Faires around 
the US 


hile we’ve seen the 

Raspberry Pi used in 

medical applications 
before, it’s still quite rare. We 


met Ernesto Holguin from El Paso 


in Texas at the Htouston Maker 
Faire, showing off his fantastic 
new project, and decided we had 
to talk to him about how he too 
is improving medical technology 
with the humble Pi. 


What is it you’ve made with 

a Raspberry Pi: 

I invented a device that is 
dedicated to the telemonitoring 
and drying of diabetic foot 
ulcers. The patented apparatus 
— US Patent #9775474: 
magpi.cc/vhseyj — utilises the 


Raspberry Pi 3 to inspect, dry, 

take images, and communicate 

other vital sign information with 

clinicians and family members. 

It uses a Python-programmed 

application, forming a team 

approach to that person’s care. 
One in five diabetic patients visit 

a clinic/hospital for treatment 

of an ulcerative wound. From 

the time of discharge till the 

next clinician’s visit, 30+ days 

on average, a patient’s affected 

skin is not monitored, resulting 

in worsening ulcers/wounds, 

leading to amputations and 

deaths. Worsening of wounds 

primarily occurs due to the 

improper monitoring and drying 

in-between the toes. The diabetic 


Ernesto built the platform 
completely from scratch 


raspberrypi.org/magpi 


It doesn't look 


very pretty, but 
it's a crucially 
important piece 
of medi-tech 


population suffers from high risk 
for infection, poor eyesight, and 
limited mobility. Limited family 
support and transportation adds to 
improper healing. My device would 
allow for patients to daily inspect 
their own feet ... with the clinician 


These images 
show the 3D model 
made for the 
patent application 


Engineering Symposium 2018, 
and Mini-Maker Faire Galveston 
2018. It has gone through multiple 
airports, mail deliveries, and 
vigorous car trips. The Raspberry 
Pi continues to perform true to its 
original intentions. 


I have five more projects lined 
up where I will be utilising the 


Raspberry P1 


overseeing the progress, from the 
comfort of the patient’s home. 
Earlier medical intervention will 
be established, leading to better 
patient outcomes. 


Why the Raspberry Pi? 

The Raspberry Pi computer is 

small, fast, efficient, and is priced 
at an optimal value. It is pliable, 
allowing other applications to be 
easily added. Iam a proud member 
of MakerNurse Community from 
MIT and they were instrumental 

in applying the Raspberry Pi with 
Python coding to my diabetic device. 


How well does it perform? 

The Raspberry Pi has worked 
consistently well while I have 
presented my device in Maker 
Faire New York 2017, Maker Faire 
Houston 2017, University of Texas 
in El Paso (UTEP) SIAM Symposium 
2017, SXSW 2018, UTEP’s System 
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How else do you think the 
Raspberry Pi can be used in 
medical tech? 

The Raspberry Pi can be utilised 

in any upcoming medical device 
inventions in which the reliability 
of the system will be instrumental. 
The low-priced Pi will reduce the 
cost of production and make it 
more affordable to consumers. 


Any future project plans using a Pi? 
Yes! I have five more projects 

lined up where | will be utilising 
the Raspberry Pi. They’re projects 
that will be used to improve 

the monitoring of patients and 
water conservation. 

Technology is always advancing 
and making it more affordable to 
Start projects people only dreamed 
of in the past. The Raspberry Pi 
is leading this new wave and has 
catapulted the idea I had in 2003 
to a reality. 


Ernesto's machine isn't just a neat thing he shows off 
at Maker Faires — the benefits of it have been well 
acknowledged with plenty of awards to back it up: 


- Infy Maker Award winner — June 2017 


* MCA Proof-Of-Concept winner — July 2017 


* Houston's Maker Faire: Merit Award winner — 
October 2017 


He’s also been featured in local and national news 
outlets for his efforts. Find out more about the device 
at his website: otenmedical.com. 
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COMMUNITY PROFILE 


PI WARS FRANK 


How one primary school teacher’s love of ICT made 
her legendary in the Raspberry Pi community 


y day, Sway Grantham is 
pe primary school teacher 
and Specialist Leader in 
Education for Primary Computing 
and ICT in Milton Keynes. 

Outside of her day job, Sway has 
gone above-and-beyond to become 
one of the biggest names in the 
Raspberry Pi community. 

She was invited as a ‘lead 
learner’ to attend the first ever 
Raspberry Picademy, becoming a 
Raspberry Pi Certified Educator, 
Sway organises TeachMeets in 
Milton Keynes and Northampton. 
She also hosts a Raspberry Pi 
networking group and supports a 
local CamJam. 

“I decided to be a teacher when 
I was about eight,” says Sway. At 
least that was according to her 
mum (“yes, Iam that cool,” she 
tells us). 


“However, | didn’t want to 
narrow my options that would keep 
me in teaching forever, sol! dida 
Psychology and Computing degree 
at the University of Kent.” 

Sway was the only person in her 
entire university to do a Psychology 
and Computing combination, 
but it meant she could focus on 
developmental and educational 
psychology as well as her interest 
in computing. 


lIlustrious company 
After becoming a primary school 
teacher, she became a Member 
of the Raspberry Pi Foundation. 
“ve been a Member for a couple 
of years, and it was a surprise 
to be asked! 

“1 do suffer a little from 
imposter syndrome when you see 
the other members (cough...Tim 


We can assure you this 
is part of a lesson, not 
an order to the students 


Rignt~)\--\\a— 
students have 
made imaginative 
projects. But this 
one may turn out 
to be dangerous 
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As a Member of the Raspberry Pi 
Foundation, Sway gets to influence the 
learning projects in the organisation 


Tim can use the Raspberry Pi an 
entertain himself and others too so 


Peake, cough). But I feel pleased 
that someone is representing 
primary education and is able to 
inform those who aren’t in school 
every day what it’s like in that 
environment — usually this is not 
what people imagine.” 

Sway is a keen maker, but her 
focus is on educating children 


I've been incredibly lucky with 
the support I've gotten from 
the community over the years 


rather than building for its own 
sake. “I am more of a functional 
user,” she tells us. “I make 
things that help me teach stuff as 
opposed to cool projects. 

“T am proud of everything that a 
child I teach creates,” adds Sway. 
“From alone LED that starts 
flashing, to a stop-motion camera 
program. For someone in a primary 
school to achieve such things is 
really amazing and it opens so 
many doors in their future.” 


Opening doors 

These projects help Sway to 

enrich the lives of her children. 
“T’ve seen the doors these skills 
can open and I want everyone to 
have the opportunity to try them. 
Particularly in primary schools, the 
main thing we need to do is show 
children what’s possible — even if 
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they’re not ready to achieve that 
yet — and plant seeds that grow 
into ambitions for the future. The 
broader the experiences, the more 
rounded an individual you can 
become and Computer Science 
(CS) is my way to reach these 
children. It’s so diverse, you can 
like computer games, music, art, 


science, etc. and there’s still a CS- 
related project that can engage you. 
“T’ve been incredibly lucky,” 
says Sway, “with the support I’ve 
gotten from the community over 
the years. When | taught my first 
ever programming lesson, in 2013, 
I did it to win some Raspberry 
Pi devices. I had no idea what | 
was doing. I did it anyway. The 
amount of times I’ve had to tweet 
someone and ask what I’ve done, 
or what something means, or how 
do I do something, and there’s 
always someone willing to take 
the time to explain it. Ican only 
offer the opportunities I offer to 
children because those people 
were patient enough to explain it 
to me. Everyone should aspire to 
be a lifelong learner and ensure 
everyone knows you’re still 
learning too!” 


SWAY GRANTHAM 


Left Sway 
attended the first 
ever Raspberry 
Picademy, 
becoming a 
Raspberry Pi 
Certified Educator 


Left Sway’'s 

pet projects 
include the 
code for a stop- 
motion camera 


picamera.PiCamera () camera: 
Camera. otart preview) 
GPIO.wait_for _edge(i?, GPIO.PALLING) 
time . sleep iS) 

canera,.capture(' (home /pi /Derktoy 
camera. stop preview () 


PI TOWERS 


Sway was invited (along with 
other Digital Leaders) to Pi 
Towers for a day exploring and 
learning whilst sharing their 

own ideas and opinions with the 
Foundation. “When | explained 
the potential trip to the children, 
they were excited,” recalls Sway. 
“When | handed out the letters, 
they nearly exploded. All the slips 
were back the following day - 
digital leaders were queuing 

at my door before school start 
and it wasn't even first come, 
first served!" 
magpi.cc/wPuHYv 


Left There's 
more to primary 
education than 
conkers and 
times tables 
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EVENT CALENDAR 


Find out what community-organised, Raspberry 
Pi-themed events are happening near you... 


ROANOKE a 
RASPBERRY JAM © ~~ 


5 


4 DALLAS YOUNG MAKERS CLUB 


Want a Raspberry Jam in your 
area? Want to start one? Email 
Ben Nuttall to find out more: 

ben@raspberrypi.org 


OLIVE BRANCH 
RASPBERRY JAM 


ry @ SHE PI JAM 


— 
SFO Ime JhyAln le VEIN Is 
OLIVE BRANCH DUBLIN RASPBERRY PI JAM ROANOKE RASPBERRY JAM 
RASPBERRY JAM When: Saturday 11 August When: Saturday 8 September 
When: Saturday 28 July Where: Science Gallery Dublin, Where: Roanoke South County 
Where: B.J. Chain Public Library, Dublin, Ireland Library, Roanoke, VA, USA 
Olive Branch, MS, USA magpi.cc/jXkusP magpi.cc/PAdbMf 
magpi.cc/WxeYYR The first Dublin Raspberry Pi A robotics-focused Raspberry 
Join the Olive Branch team for Jam will have something for Jam, with demon Pi robots 
a free family event showing off everyone, from beginners to and a chance to build a GoPiGo 
awesome inventions. dedicated Pi hobbyists. in teams. 
SHE PI JAM DALLAS YOUNG PRESTON RASPBERRY JAM 
When: Sunday 5 August MAKERS CLUB When: Monday 6 August 
Where: Herbert Macaulay Way, When: Saturday 11 August Where: Media Innovation Studio 
Lagos, Nigeria Where: J. Erik Jonsson Central magpi.cc/OYbCLu 
magpi.cc/jeLRKx Library, Dallas, TX, USA A community of people who 
An initiative to build and magpi.cc/UTJrCh meet to learn, create, and 
train a community of young A new, regular free workshop share the potential of the 
women makers with the use of for kids aged 8-18 that covers Raspberry Pi. 
Raspberry Pi. robotics and Raspberry Pi! 
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CORNWALL TECH JAM 
When: Saturday 8 September 
Where: Bodmin Library, 
Bodmin, UK 
cornwalltechjam.uk 
Learn about programming 
on platforms including 
Arduino and Raspberry Pi, in 
various languages. 
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NORTHERN IRELAND 
RASPBERRY JAM 
When: Saturday 8 September 


Teaching, Belfast, UK 
magpi.cc/yNUGdg 


having fun making! 


Where: School of Maths and Physics 


This free event involves tinkering, 
coding, electronics, and generally printed worksheets, stickers, flyers, and more. 


Get the guidebook here: magpi.cc/2qSDHfQ 


WE'VE SOME OF 
THE AREAS 
CAN YOU HELP OUT? 


RASPBERRY JAM ADVICE 
PROMOTING YOUR EVENT 


Our volunteers have eee that say ‘Jam ey @ ay Ly A 
Maker’ on them. Sometimes we have # - 4 ~ y ow 
lanyards. Tim and | tend to wear our purple ¢ 

CamJam polo shirts. They weren't cheap, 


a a RY 4 
but we do stand out! ll 
g°* 
a= 
6 | 


yl 


Michael Horne 
Cambridge Raspberry Jam e RASPBERRY 


ne s AN IV “ 
Every Raspberry Jam is entitled to apply for a : = 
Jam starter kit, which includes magazine issues, YYIDEBOOK 
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I love what the Raspberry Pi 
Foundation does, and have 

used a few of the projects on 
their website. I keep hearing 
about some kind of free teacher 
training, though - what exactly is 
this? Do I need to be a teacher to 
take it: 

Ellen Y 


You’re thinking of Picademy, 
which is currently held in the 
UK and North America by the 


LETTERS 
TEACH ME 


Foundation at various times and 
locations — check out the website 
for more info: magpi.cc/picademy. 
As long as you’re helping kids 
learn about computing, you’re 
eligible to apply for a session. 

If there’s not an event you 
can go to, you can always do the 
online courses on FutureLearn 
(you can find the links on the 
Picademy page linked above) 
which will give you more 
teacher-focused training. 


3D-PRIN TABLE 


I loved the article on how to 
build a 3D printer in issue 69. 
However, now I’ve built it and 
tested it to make sure it works, 

I find myself unsure what to 
print! While I occasionally 
stumble across cool stuff on 
Thingiverse, I’d like to get some 
bits for my future Pi projects. 
Do you have any suggestions? 


Bill C 


Well, you can always get a 
3D-printed case for your 
Raspberry Pi - including a 
wonderful 3D-printable version 
of the Astro Pi case that is the 
Same size and shape as the cases 


The PiGRRL projects 
are great uses of 
3D-printed parts 
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used for the Raspberry Pi boards 
up on the ISS. You can find the 
details on how to do it here: 
magpi.cc/fwxXmO. 

There are also the PiGRRL cases 
that you can use to make your 
own handheld retro console using 
the Raspberry Pi. There are many 
versions, but we’re partial to the 
PiGRRL 2: magpi.cc/2dbpjLx. 

There’s also a brilliant recent 
article on the Raspberry Pi 
blog full of great 3D-printable 
projects and such. Find it here: 
magpi.cc/ccGmWo. 


raspberrypi.org/magpi 


=> 
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FROM THE FORUM: 


The Raspberry Pi Forum is a hotbed of conversations 
and problem-solving for the community — join in via 


raspberrypi.org/forums 


while ago I posted up about how I would 


several issues. 


like The MagPi to do a robot build over YOUR OFFICIAL RASPBERRY P| MAGAZINE 
a “@ - 


Several people liked this idea, but I was also suggestions — we are the community 
wondering what else Pi fans might like to see magazine after all! Send suggestions to 


We’re always happy to hear about article 


as a project build in The MagPi?: 

Who knows, perhaps if we can get enough 
[support] for a certain type of build, The MagPi 
people may take us up on our request (perhaps 
they could run a vote system somehow on here 
- I did think of doing a poll, but would want to 


magpi@raspberrypi.org and we’ll give 
them a look over! Otherwise, we may 
just use the idea of creating a poll to 
get an idea of what you folks would like 
to see more of. 

Otherwise, if you’re looking for a 


see what other ideas people have first)? robot build in the magazine, we did do 
Otherwise, it would be fantastic if The MagPi _one in issues 51 and 52 with the Tiny 
did a wheeled robot build over a couple of robot from Brian Corteil. QrIy 


issues Or SO. 


Torcrayth 


I’ve always been inspired by the 
high-altitude ballooning (HAB) 
that people have done with the 
Raspberry Pi, but have always 


found the process a little daunting. 


Are there any plans for a future 
article on making your own HAB 
with a Pi? Or are there any helpful 
resources you know of that would 
make it easier for a beginner? 
Benjamin 


There’s a lot to launching a 
HAB that we may not be able to 


raspberrypi.org/magpi 


HIGH 


If you're interested in an article about building 
robots, check out issue 51 of The MagPi 


THE ORLY £5 By i haepe - 
MAGA SINE WRITTEN By THE ACENat HAY Ale 
“DMM LINE ¢ 


adequately cover in the magazine 
(especially in regard to filling up 
the balloon), but we may give it a 
go one day! 

At the very least, we can 
point you towards the new 
developments going on with 
creating new software for 
Skycademy — the Raspberry 
Pi Foundation’s free teacher 
training course to learn about 
HABs. You can read more about 
it on the Raspberry Pi blog here: 
magpi.cc/MoZIYM. 


The new SkyGate is the future of Skycademy 
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CAN YOU HELP INSPIRE = 
THE NEXT GENERATION & 


OF CODERS? 


educators who run free coding clubs for 
young people aged 9-13. 


ra! To find out more, join us at 
Code Club is part of the Raspberry Pi Foundation. Registered Charity Number 1129409 C5 


In association with 


MODMYPI 


ONE OF 


RASPBERRY PI 
ROBOT KITS! 


We reviewed the YetiBorg in issue 
71 and think it's a great kit for 
people thinking about getting 

into robotics, thanks to a robust 
build quality and powerful 


programming library. . 


& 


~ 
I 


Enter now at magpi.cc/win 


Terms & Conditions 


Competition opens on 25 July 2018 and closes on 31 August 2018. Prize is offered to participants worldwide aged 13 or over, except employees of the Raspberry 
Pi Foundation, the prize supplier, their families or friends. Winners will be notified by email no more than 30 days after the competition closes. By entering the 
competition, the winner consents to any publicity generated from the competition, in print and online. Participants agree to receive occasional newsletters from 
The MagPi magazine. We don't like spam: participants’ details will remain strictly confidential and won't be shared with third parties. Prizes are non-negotiable 
and no cash alternative will be offered. Winners will be contacted by email to arrange delivery. Any winners who have not responded 60 days after the initial 
email is sent will have their prize revoked. This promotion is in no way sponsored, endorsed or administered by, or associated with, Instagram or Facebook. 
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THE FINAL WORD 


ne of my favourite Raspberry Pi accessories 
is the tried-and-true Camera Module. Pi 
enthusiasts have been using this legendary 
component in their projects since the early days of 
the Raspberry Pi and I still see tons of great Pi-based 
camera projects coming out on a regular basis. 

I especially like the Camera Module because it 
can be used in so many different ways. It’s great for 
tweeting photo booths, time-lapse projects, stop- 
motion rigs, security cameras, and wildlife monitoring 
projects. Makers also give new life to old antique 
cameras by retrofitting them with a Camera Module 
and a Raspberry Pi Zero, which is perfect for this 


MATT RICHARDSON 


Matt Richardson is the Executive Director of the Raspberry 
Pi Foundation North America and author of Getting Started 
with Raspberry Pi. Contact him on Twitter @MattRichardson. 


» THE MIGHTY 
» CAMERA MODULE 


Matt Richardson shares his favourite Raspberry Pi camera projects 


that information to a massive dataset of doodles from 
Google. Those doodles make up a cartoonish version of 
the snapped frame. The result is printed out the front 
of the camera, as though it were a Polaroid. 


Saving lives 

The Raspberry Pi Camera Module isn’t only used for 
creative technology projects. It’s also doing serious 
work and saving lives. Henry J Feldman, Chief 
Information Architect at Harvard Medical Faculty 
Physicians, created a Raspberry Pi-based robot that 
tests 3D-printed airway stents to ensure they’re 
durable before they’re implanted into a patient 


Some of the most unusual Raspberry P1 
projects I've seen use the Camera Module 


purpose because of its small size. My friend Becky 
Stern used a Camera Module in an antique camera so 
that it makes animated GIFs and uploads them to the 
web via WiFi. 


Curious projects 
Some of the most unusual Raspberry Pi projects I’ve 
seen use the Camera Module. For example, Dries 
Depoorter in collaboration with Max Pinckers created 
what he calls the Trophy Camera (magpi.cc/NPdreS). 
This Al-powered camera is trained with all of the 
winning photographs from the World Press Photo of 
the Year competition. Only if the photo you take has 
similar patterns to the award-winning photos will 
it be saved and uploaded to a dedicated website. I’ve 
never seen a camera like that before. 

Recently Dan Macnish created a project called Draw 
This. It uses the Raspberry Pi 3, a Camera Module, 
and a thermal printer (another one of my favourite 
components). After you snap a photo, it’s passed 
through a machine-learning model that identifies 
objects and their position in the frame. Then it submits 
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(magpi.cc/nlvoET). They test the stents by squeezing 
them 300000 times. The Raspberry Pi controls a 
servo to repeatedly squeeze the stent, and the Camera 
Module takes a photo of the stent after each squeeze. 
The machine uses a computer vision algorithm 

to detect if the stent has failed and will stop the 
squeezing if so. This gives their team the opportunity 
to examine how it failed and iterate on the design. 

At World Maker Faire New York a few years ago | 
met Joe Herman, who created his own Raspberry Pi- 
based telecine (magpi.cc/NGISVP), a machine used 
to convert motion picture film to digital video. Joe 
used an old 8mm film projector and outfitted it with 
stepper motors to advance the film after each frame 
is captured with the Camera Module. The Pi can then 
string those frames together to create video. 

As you can see, there are so many amazing ways 
to use the Raspberry Pi Camera Module in a project. 
If this column has inspired you to start making 
your own, be sure to check out magpli.cc/tutorials 
and rpf.io/projects to see an abundance of camera- 
enabled projects. Don’t forget to say cheese! 
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THE Official 
RASPBERRY PI 
EGINNER'S BOOK 
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THE EASY WAY! 


Pi Zero W computer 


Official case with three covers 
USB and HDMI adapters 

8GB microSD card 

116-page beginner’s book 
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The pocket-sized desktop computer! ____ ——— 
) PI ZERO 


magpi.cc/store 
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Build your own credit card 
sized computer 


Get started with Programming 
Set up a Media Center 


Make simple electronic circuits 


Raspberry Pi board and case 
Suit supply and HDMI cable 
re-Programmed Memory Card 
Over 40 electronic Parts 
Raspberry Pi Kit For Oummies Booklet 
@ 
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DUMMIES 


Available in Europe 
Available for worldwide shipping at: through RS Components 


$89° £69° 


US DOLLARS EXCLUDING VAT 


Raspberry Pi is a registered trademark of the Raspberry Pi Foundation. 
For Dummies and the Dummies Man logo are trademarks or registered 
trademarks of John Wiley & Sons, Inc. Used under license. RS logo is 

a registered trademark of RS Components Ltd. Canakit is a registered 
trademark of Cana Kit Corporation. 
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